PR#5: KRA ACL proposal -- merges - test_dogtag_designs

		`@@ -28,6 +28,15 @@`

		`specs/juno/*`

		`+ 10.3 approved specs:`
		`+`
		`+ .. toctree::`
		`+ :glob:`
		`+ :maxdepth: 1`
		`+`
		`+ specs/10.3/*`
		`+`
		`+`
		`==================`
		`Indices and tables`
		`==================`

specs/10.3/kra-projects.rst

file added

+482

		`@@ -0,0 +1,482 @@`
		`+ ..`
		`+ This work is licensed under a Creative Commons Attribution 3.0 Unported`
		`+ License.`
		`+`
		`+ http://creativecommons.org/licenses/by/3.0/legalcode`
		`+`
		`+ ================================`
		`+ Refined permissions for the KRA`
		`+ ================================`
		`+`
		`+ As we have expanded the role of the KRA to be able to store different`
		`+ kinds of secrets, it has become more important to be able to segregate`
		`+ secrets from each other. For example, secrets stored by IPA admins`
		`+ should only be accessible by those admins, whereas those stored by Barbican`
		`+ should be accessible only to Barbican.`
		`+`
		`+ In fact, when we add to Dogtag the ability to accept GSSAPI messages,`
		`+ it may be possible for IPA to proxy over the security context for that`
		`+ specific user. In that case, we need a mechanism to ensure that the secrets`
		`+ accessible are only those for a specific user.`
		`+`
edewata commented 8 years ago Need to clarify that GSSAPI will only be used between IPA and PKI, but not between PKI and DS, although IPA is already using GSSAPI to communicate to DS directly.
vakwetu commented 8 years ago will do.
		`+ Problem Description`
		`+ ===================`
		`+`
		`+ The way in which we access secrets in the KRA has changed. We need to be able`
		`+ to support the following flows:`
		`+`
		`+ N-Agent-mediated retrieval:`
		`+`
		`+ This is the traditional flow supported by the KRA. We need to be able to`
		`+ continue to support this flow for traditional PKI deployments, even to the`
		`+ point of being able to disable access using other flows.`
		`+`
		`+ * Agent initiates a recovery request. For the REST API, this is done through`
		`+ POST /keyrequests/retrieve.`
		`+`
		`+ * N agents approve the request. For REST, POST`
		`+ /keyrequests/{id}?action=approve`
		`+`
		`+ * Once request has been approved, the original agent retrieves the key,`
		`+ providing either apassword for a PKCS12 file or a symmetric key to wrap`
		`+ the secret. This is GET /keys/{id}`
		`+`
		`+ 1-Agent mediated retrieval:`
		`+`
		`+ This is just a subcase of the N-Agent retrieval above. We mention it in`
		`+ particular because both IPA and Barbican now use this type of access.`
		`+`
		`+ * Agent authentication is through client certificate authentication.`
		`+ * Agents have access to all secrets, independant of origin. So,`
		`+ IPA agents can retrieve Barbican secrets and visa versa.`
		`+ * This requires keeping the private key for a KRA agent on the IPA/Barbican`
		`+ server, which is a potential attack point. Once that credential is`
		`+ stolen, all secrets are compromised (unless they were pre-encrypted).`
		`+`
		`+ Direct Archival:`
		`+`
		`+ This flow is not yet supported, but presumably would become the default way`
		`+ to access secrets from IPA.`
		`+`
		`+ * IPA proxies the user's credentials using GSSAPI. After being processed in`
		`+ the relevant Tomcat Realm, a Principal is returned to the KRA servlets.`
		`+`
		`+ * Secret is stored in the KRA, along with the principal (owner)`
		`+ and a key_id is returned.`
		`+`
		`+ Direct Retrieval:`
		`+`
		`+ * IPA proxies the user's credentials through GSSAPI. After being processed`
		`+ in the Tomcat realm, a principal is returned.`
		`+`
		`+ * If the principal matches the owner, access and return the secret.`
		`+ The secret is of course wrapped for transport with a user provided`
		`+ transport key.`
		`+`
		`+ Escrow Agent Retrieval:`
		`+`
		`+ IPA has a retrieval mode (currently not implemented) that allows a secret`
		`+ to be retrieved by an escrow agent. When a vault is set up, the vault`
		`+ encryption key is encryted with the agent's private key and stored in the`
		`+ KRA. The agent then retrieves both the encrypted vault encryption key and`
		`+ the secrets.`
		`+`
		`+ From the point of view of the KRA, we need a mechanism to allow the agent to`
		`+ access the user's secret. The proposed mechanism will be through tags and`
		`+ ACLs.`
		`+`
		`+ In terms of the access methods described above, this is the desired`
		`+ end-state:`
		`+`
		`+ * CS users will continue to store encryption keys via the CA-KRA connector.`
		`+ These keys will be accessible by CS agents (who will continue to have an`
		`+ agent role) using the N-agent retrieval method. Nothing changes here`
		`+ except that CS agents will not be able to access secrets stored by other`
		`+ applications.`
		`+`
		`+ * IPA users will store secrets using the direct archival method. They will`
		`+ only be able to access those secrets for which they are the owner. They`
		`+ retrieve secrets using the direct retrieval method.`
		`+`
		`+ * IPA escrow agents will retrieve secrets using the direct access method.`
		`+ This means they will be able to retrieve secrets for which they are either`
		`+ the owner or which are permitted through tags/ACLs to access the secret.`
		`+`
		`+ * For the purposes of this design doc, the following IPA will be considered.`
		`+ A user U0 will store an IPA vault. This vault will have members U1, U2 and`
		`+ U3 (who are therefore permitted to retrieve and modify the secret. Also,`
		`+ the secret is archived by an organization's ("sales") escrow agents which`
		`+ are in escrow group EG0. All users and groups are in IPA.`
		`+`
		`+ Proposed Change`
		`+ ===============`
		`+`
		`+ Authentication`
		`+ --------------`
		`+`
		`+ Authentication will be performed using an authentication plugin that provides,`
		`+ for instance, credentials using GSSAPI. The exact authentication method`
		`+ may be determined based on the URL. I will defer the design of this module to`
		`+ the SPNEGO design document being written by Fraser. The main point though is`
		`+ that, as a result of this plugin, a principal is provided by the authentication`
		`+ plugin. This could be either an agent defined in the KRA dataabse, or a user`
		`+ (user, goup, role) in the IPA database.`
		`+`
		`+ Tags`
edewata commented 8 years ago Can we call this "permission"? "Tag" is too generic and what it really does is granting permissions.
cfu commented 8 years ago I actually think "Tag" is more appropriate between the two. If "Tag" means some other things that could confuse anyone, words like "Label", "World", "scope" etc. to differentiate the realm or scope of the relevance could be used.
vakwetu commented 8 years ago I think "tag" is more appropriate too. We could use "Label" if that is less confusing. We are labeling or tagging a secret to be of a specific type, so that we know how to apply permissions rules to it. tag != permission tag => (implies) set of permissions What other use of "tag" are we trying to disambiguate against?
edewata commented 8 years ago The concern is if there's no well-defined usage people might use tags for things other than permission. When that happens it could interfere with how the permission works, and it would be harder to separate permission tags and non-permission tags later.
		`+ ----`
		`+`
		`+ When a secret is stored, the following fields will be added to each secret:`
		`+`
		`+ * tags - user defined label that is used to determine which authorization`
		`+ plugin should be invoked. We expect tags to be something like "ipa" or`
		`+ "barbican" or "rhcs". Creating or deleting tags is a KRA administrator`
		`+ operation. Tagging a specific key is an operation reserved to the owner(s)`
		`+ of the key. We can also add a parameter to tag a key when it is created,`
		`+ rather than performing these operations in two steps.`
		`+`
		`+ * owner - This will be populated by Dogtag when the secret is stored`
		`+ as the principal returned by the Tomcat realm. This is a multi-valued`
		`+ parameter. An interface will be provided for owners to add other owners.`
cfu commented 8 years ago If this is going to be a field that requires external management, then perhaps the "owner" field should be outside of the CS system. And perhaps change this field to be "creator" instead, a single value field that is populated when the record was first created.
vakwetu commented 8 years ago I'm ok with this suggestion. If IPA or another app wants to have multiple "owners", then they can -- and in fact do -- keep track of it. Endi?
edewata commented 8 years ago Since we won't be using GSSAPI between PKI and DS, there is actually no need to have an owner/creator field in the DS since all secrets will only be accessed by pkidbuser. If we plan to have users other than pkidbuser to access the secrets, then it would make sense to have owner(s)/creator field with an ACL that grants certain permission.
edewata commented 8 years ago Also, since we won't be using GSSAPI between PKI and DS, there is no need to store tags in the DS either. The PKI server can utilize an authorization plugin to check with IPA if the user has access to certain secrets (which can be determined by IPA vault ownership/membership).
		`+`
		`+ Authorization`
		`+ -------------`
		`+`
		`+ Access control is then performed by an authz plugin. One could, for instance,`
		`+ retrieve any tags associated with a KeyRecord, and then perform a different`
		`+ check depending on the tag. So, for instance, if one of the tags is "IPA",`
		`+ then we would invoke an IPAAuthzPlugin. This plugin would contact the`
		`+ IPA server - maybe through some REST servlet that is hosted in the IPA server -`
		`+ and ask whether or not access is allowed.`
		`+`
		`+ The idea here is that the application (in this IPA) knows the users, roles`
		`+ and groups, amd also an acls that determine access. So, for instance, the KRA`
		`+ would contact the IPA server and provide the secret_id, and principal (user,`
		`+ groups, role). The IPA server would look up the vault corresponding to the`
		`+ secret_id, and determine access based on which principals are in a members`
		`+ list or an owner's list. It would return YES/NO to permit access.`
		`+`
		`+ For applications like Barbican, a group-based authz plugin may be sufficient.`
		`+ This plugin would check if the returned principal was part of a particular`
		`+ group.`
		`+`
		`+ Use Cases`
		`+ ---------`
		`+`
		`+ Below is a description of how each of the above use cases will be`
		`+ satisfied using the mechanism above:`
		`+`
		`+ * N-agent retrieval: This will not be affected by the changes in`
		`+ this design. Secrets will continue to be stored by agents through`
		`+ the CA-KRA connector, and retrieved using the N-agent retrieval`
		`+ request mechanism. Note though that we need to restrict CS agents`
		`+ from being able to access secrets stored by other applications.`
		`+ A couple of mechanisms that come to mind to do this are:`
		`+`
		`+ * Tagging all existing CS secrets with a special "cs_application"`
		`+ tag, and adding ACLs to allow CS agents to access secrets with`
		`+ that tag.`
cfu commented 8 years ago I actually prefer this one instead of special casing in the other method.
vakwetu commented 8 years ago It does make things cleaner, although there are migration considerations here. We don't want to disable existing customer's access to their secrets if a migration script failed to run. Most likely, what we'll end up doing is having a migration script that adds the special tag, and then, on completion, sets a config flag that disables the special casing.
		`+`
		`+ * Modifying the key request servlets to explicitly exclude those keys`
		`+ which are tagged.`
		`+`
		`+ * IPA vault:`
		`+`
		`+ We will illusrate the following example. IPA creates a vault for user U0`
		`+ containing multiple secrets that is accessible to a set of users {U1, U2, U3}.`
		`+ These users can read the secret but cannot overwrite it. In addition, the`
		`+ vault is escrowed by the organization's escrow officer group E0.`
		`+`
		`+ * During the IPA install, the KRA administrator would define a tag "ipa"`
		`+ and register and configure the IPAAuthzPlugin.`
		`+`
		`+ * User U0 creates a vault secret though IPA. IPA proxies U0's credentials`
		`+ to Dogtag through GSSAPI, and will create a secret corresponding to a vault`
		`+ using direct archival. The owner field will be populated with the U0`
		`+ principal by the Dogtag application. The secret will also be tagged as "ipa".`
		`+`
		`+ * When the secret is retrieved by a user UX, the user's credentials are`
		`+ proxied to Dogtag through GSSAPI and are extracted by the authentication`
		`+ plugin. Because the secret is tagged as "ipa", the IPAAuthzPlugin is invoked.`
		`+ This plugin contacts the IPA server and provides the secret_id and user`
		`+ principal (users, groups, roles) and access type and queries whether`
		`+ access should be granted.`
		`+`
		`+ * A couple of ways to contact the IPA server come to mind.`
		`+`
		`+ * One way is to create a new access-control REST web service on IPA.`
		`+ This service would look up the vault_secret_id from the secret_id, and`
		`+ then attempt to access the vault secret with the relevant principal`
		`+ (and operation).`
		`+`
		`+ * Another way is to add a user defined metadata field to the the key record`
cfu commented 8 years ago It is probably fine to have metadata put in the key record at the time of creation, as long as no further management needed after the creation.
vakwetu commented 8 years ago Because the metadata is user-defined, I don't think we can enforce that it will not change. IPA, for example, will store the vault_secret_id here, and while that does not currently change, it seems unreasonable for us to require them to create a brand new secret and remove the old one in order to change it. This is just defining a user-defined metadata field -- why does it have to be immutable?
		`+ in the KRA. IPA would set the vault_secret_id in this field. Then the`
		`+ plugin could attempt to query the IPA database using the proxied credentials.`
		`+`
		`+ * Barbican access:`
		`+`
		`+ * When Barbican is configured to interact with the KRA, a KRA`
		`+ administrator will create a "barbican" tag.`
		`+`
		`+ * The adminstrator will also create a barbican user and group of barbican`
		`+ agents. If the agents group already exists, the barbican user will be added`
		`+ to it. These users and groups will be added to the KRA database.`
		`+ Note that this user is NOT a KRA agent.`
cfu commented 8 years ago I don't think non-CS role users should go into the KRA database. The day-to-day management of non-CS users should be kept out of the core CS.
vakwetu commented 8 years ago Eventually, barbican users will be defined in an IPA database and the barbican-dogtag-plugin will use kerberos/GSSAPI to talk with Dogtag. There is a lot of work needed to get there though. In the interim and because it is possible to deploy the KRA with Barbican outside of IPA -- the simplest possible scenario to promote adoption -- we need to add the user to the KRA DB. Note that we now need to consider CS as just another (albeit important) application that is using the KRA. If we have CS users, why not barbican users?
		`+`
		`+ It remains an open question as to whether these users/groups should be`
		`+ created in IPA if an IPA store is available. In order for this to be`
		`+ viable, the Dogtag plugin in Barbican would need to be configured to`
		`+ interact with Dogtag either through IPA or using GSSAPI.`
		`+`
		`+ * Optionally, an authz plugin can be configured for Barbican-tagged secrets.`
		`+ This plugin would simply check if the returned principal is part of the`
		`+ Barbican group.`
cfu commented 8 years ago yes
		`+`
		`+ * Secrets are stored by the Barbican user using direct archival. This will`
		`+ store the owner of the barbican user principal as the owner of the secret.`
		`+ The secret should also be tagged as a Barbican secret.`
		`+`
		`+ * Retrival of the secret is done using direct retrieval. If an authz plugin`
		`+ is enabled, the "barbican" tag will trigger the Barbican authz plugin, which`
		`+ would check if the principal is part of the Barbican group.`
		`+`
		`+ * Otherwise, we would fall through to an authz check as to whether the principal`
		`+ is the owner of the secret,`
		`+`
		`+ Alternatives`
		`+ ------------`
		`+`
		`+ None.`
		`+`
		`+ Data model impact`
		`+ -----------------`
		`+`
		`+ The following optional fields will need to be added to the keyRecord object:`
		`+`
		`+ * owner (does an owner attribute already exist and what is populated there?)`
		`+`
		`+ * tag (which can be multi-valued, to allow the potential access of secrets`
		`+ through multiple applications)`
		`+`
		`+ If we consider adding user metadata to the secret - like the vault_secret_id`
		`+ to allow the IPA AUthz Plugin to access the IPA DB directly, then we may need`
		`+ to add fields/tables to that effect.`
		`+`
		`+ A new suffix will need to be added for tags (ou=tags, ou=kra, {rootSuffix}).`
		`+ Under this suffix, tag objects will need to be stored. Tag objects will`
		`+ have at a minimum a cn and description.`
		`+`
		`+ REST API impact`
		`+ ---------------`
		`+`
		`+ An interface will need to be added to add and remove tags.`
		`+`
		`+ * Add or modify tags`
		`+`
		`+ * Add a tag to be used in ACIs for secrets. This tag is user defined.`
cfu commented 8 years ago I was hoping that tags are static. Again, I'm hoping to keep day-to-day management of these out of the CS authorities.. Could the tag be static, and you have another external acl to specify whether an app has to a specific tag or not?
vakwetu commented 8 years ago Consider that several applications need to use the KRA to store secrets. Right now we have three -- CS, IPA Vault and Barbican. Each application needs to contact the KRA administrator to: a) register a plugin for authz b) register tag(s) that map to that authz plugin This must be done in co-ordination with the KRA administrator to ensure that the apps do not use the same tag. This is just adding an interface that can be used by KRA admins to do this task, rather than having to go to the console (which we are trying to deprecate, remember?). It also allows apps to be added post-install possibly without server restart.
vakwetu commented 8 years ago We don't expect this to be a daily occurrence. We do expect though, that this should be made easy for the admin to do.
		`+ If a tag needs to be updated, it should be removed first. Otherwise,`
		`+ an admin would not know that he is overwriting an existing tag that`
		`+ probably occurs in existing ACLs.`
		`+`
		`+ * PUT /kra/tags/{foo}`
		`+`
		`+ * Returns 201 (Created) on success`
		`+`
		`+ * Returns 409 (Conflict) if the tag already exists.`
		`+`
		`+ * Body of the request is a json blob containing "description"`
		`+`
		`+ * Request limited to KRA admins.`
		`+`
		`+ * Remove tag`
		`+`
		`+ * Remove a tag. This tag is user defined.`
		`+`
		`+ * DEL /kra/tags/{foo}`
		`+`
		`+ * Returns 204 on success`
		`+`
		`+ * Returns 404 if the ACI does not exist`
		`+`
		`+ * Request limited to KRA admins.`
		`+`
		`+ * List tags:`
		`+`
		`+ * GET /kra/tags`
		`+`
		`+ * Request can be run by anyone.`
		`+`
		`+ * Get tag:`
		`+`
		`+ * GET /kra/tags/{foo}`
		`+`
		`+ * Request can be run by anyone.`
		`+`
		`+ We will also need an interface to configure and register authz plugins, and`
		`+ associate them them with tags. This would be restricted to KRA admins.`
cfu commented 8 years ago yes. Overall, I believe that any application specific components, e.g. authentication and authorization are best to be implemented with plugin framework; To maximize the flexibility of a product, its best to keep application-specific code/data outside of the core (non-plugin) areas. That's why I am making the suggestions that I have made as far for this design.
vakwetu commented 8 years ago Exactly. But tags are the way we associate authz plugins with specific keys. We need to manage those just as we need to manage which authz plugins are registered. You could say that adding and mapping a tag is part of registering an authz plugin.
		`+`
		`+ The current KeyResource only exposes interfaces for the agent to interact`
		`+ with the system (via /agent/keys). We will need to expand this interface`
		`+ to provide direct archival and retrieval for all users.`
		`+`
		`+ So, we will need to add methods to archive, list and retrieve keys, as well`
		`+ as modify certain attributes like the members and tags. Fortunately, because`
		`+ the old N-agent mechanisms exist under /agent/keys, and the new mechanisms`
		`+ exist under /keys, there should be no conflicts.`
		`+`
		`+ In fact, we should include a parameter that allows deployers who do not`
		`+ want to permit direct access to shut down /keys.`
		`+`
		`+ All of the /keys operations require authentication either through GSSAPI`
		`+ or client certificate.`
		`+`
		`+ Operations to be added include:`
		`+`
		`+ * GET /keys - list keys to which I have access. Returns a KeyInfoCollection.`
		`+`
		`+ * GET /keys/{key_id} - returns the metadata for the key. Returns a KeyInfo.`
		`+`
		`+ * POST /keys/retrieve - retrieve a key.`
		`+`
		`+ * This operation is a POST operation because we need to provide a`
		`+ transport-key wrapped symmetric key or passphrase to wrap the`
		`+ returned key. This is too large to include in Query headers.`
		`+`
		`+ * Just like the agent/keys/retrieve counterpart, we pass in the JSON`
		`+ representation of a KeyRecoveryRequest, and expect the JSON for a`
		`+ KeyData object to be returned.`
		`+`
		`+ * GET /keys/{key_id}/tags - List tags`
		`+`
		`+ * PUT /keys/{key_id}/tags/{tag_id} - add a tag to the secret. Returns 400`
		`+ if the tag does not exist.`
		`+`
		`+ * DEL /keys/{key_id}/tags/{tag_id} - delete a tag from the secret`
		`+`
		`+ * POST /keys - archive a secret. Passes in a ResourceMessage.`
		`+`
		`+ Security impact`
		`+ ---------------`
		`+`
		`+ Security of the system should increase significantly. While we have`
		`+ expanded the pool of protential clients to the KRA to include end-users,`
		`+ rather than just agents, we have restricted the scope of what users`
		`+ (even agents) can access.`
		`+`
		`+ Secrets should only be accessible for owners and members of the secret, as`
		`+ well as those to whom we have explicitly designated access. That access`
		`+ is strictly prescribed by acls defined by administrators.`
		`+`
		`+ Moreover, by not relying only on agents to perform archival and retrieval`
		`+ operations, we can now audit exactly who is accessing or storing secrets.`
		`+ Previously, we only knew which agent was performing the operation and relied`
		`+ on the agent to keep records as to who accessed or stored a key.`
		`+`
		`+ Previously, because we depended on agents to access and store the keys,`
		`+ and because agents were able to access all keys, the loss of an agent`
		`+ credential compromised all the keys. With the new ACIs, the loss of an`
		`+ agent credential does not expose all of the keys.`
		`+`
		`+ And by using tags and ACIs, we can regulate and prevent one application`
		`+ from seeing another applications secrets.`
		`+`
		`+ Notifications & Audit Impact`
		`+ ----------------------------`
		`+`
		`+ We need to ensure that all the new interfaces are completely audited.`
		`+`
		`+ Command Line Client Impact`
		`+ --------------------------`
		`+`
		`+ Python and Java client libraries will have to be modified to add the`
		`+ new interfaces. In addtion, clients like the pki CLI and python clients`
		`+ will need to be modified to do GSSAPI authentication.`
		`+`
		`+ Other end user impact`
		`+ ---------------------`
		`+`
		`+ Both IPA and the Barbican client will need to be modified to take advantage`
		`+ of this work. It should be noted though that as the old agent mechanism`
		`+ is still supported, there should be no interruption in functionality when`
		`+ using either old or new clients with an updated server.`
		`+`
		`+ Performance Impact`
		`+ ------------------`
		`+`
		`+ There will be more interaction - particularly with the IPA database to determine`
		`+ whether access is permitted. Thats part of the price to payt for greater`
		`+ access control granularity though.`
		`+`
		`+ On the other hand though, direct access makes the process simpler -`
		`+ no more creating and acting on archival and retrieval requests.`
		`+`
		`+ Cloning Impact`
		`+ --------------`
		`+`
		`+ As ACIs are replicated across clones, there should be no impact on cloning.`
		`+`
		`+ Other deployer impact`
		`+ ---------------------`
		`+`
		`+ TBA.`
		`+`
		`+ Migration scenarios will be considered later, particularly with regard to`
		`+ IPA. Scripts will have to be written to add owner fields to the existing`
		`+ IPA vault owners.`
		`+`
		`+ Barbican is not yet widely deployed, and there are fewer changes here in`
		`+ any case.`
		`+`
		`+ One thing that will simplify migration is that currently, there are no`
		`+ mixed systems - ie. systems with Barbican, IPA and CS data. That simplifies`
		`+ the migration scripts because we need not try to figure out which`
		`+ keys belong to which application.`
		`+`
		`+ Developer impact`
		`+ ----------------`
		`+`
		`+ TBA during implementation.`
		`+`
		`+ Implementation`
		`+ ==============`
		`+`
		`+ Assignee(s)`
		`+ -----------`
		`+`
		`+ Primary assignee:`
		`+ vakwetu or ftweedal`
		`+`
		`+ Other contributors:`
		`+ edewata`
		`+`
		`+ Work Items`
		`+ ----------`
		`+`
		`+ To be completed once the design has been approved.`
		`+`
		`+ Dependencies`
		`+ ============`
		`+`
		`+ * These changes require Dogtag being modified to accept GSSAPI authentication.`
		`+ That design is being written by Fraser.`
		`+`
		`+`
		`+ Testing`
		`+ =======`
		`+`
		`+ More details to be added later, but we will need to be sure that`
		`+ - existing CS tests continue to pass`
		`+ - existing Barbican and IPA instances continue to work`
		`+ - migrated Barbican and IPA instances continue to work.`
		`+ - functional tests are added for all interfaces.`
		`+`
		`+ Documentation Impact`
		`+ ====================`
		`+`
		`+ Top-level and client docs will need to be modified to document this new access`
		`+ mechanism. Man pages and client library (API) documetation will also need to`
		`+ be modified.`
		`+`
		`+ References`
		`+ ==========`
		`+`
		`+ None`

specs/template.rst

file modified

+29 -60

		`@@ -4,17 +4,11 @@`

		`http://creativecommons.org/licenses/by/3.0/legalcode`

		`- ==========================================`
		`- Example Spec - The title of your blueprint`
		`- ==========================================`
		`+ ==================================================`
		`+ Example Design Doc - The title of your Design Doc`
		`+ ==================================================`

		`- Include the URL of your launchpad blueprint:`
		`-`
		`- https://blueprints.launchpad.net/barbican/+spec/example`
		`-`
		`- Include the URL of your client blueprint:`
		`-`
		`- https://blueprints.launchpad.net/python-barbicanclient/example`
		`+ http://pki.fedoraproject.org/wiki/PKI_Feature_Template`

		`Introduction paragraph -- why are we doing anything? A single paragraph of`
		`prose that operators can understand.`
		`@@ -25,10 +19,6 @@`

		`* Please wrap text at 79 columns.`

		`- * The filename in the git repository should match the launchpad URL, for`
		`- example a URL of: https://blueprints.launchpad.net/barbican/+spec/awesome-thing`
		`- should be named awesome-thing.rst`
		`-`
		`* Please do not delete any of the sections in this template. If you have`
		`nothing to say for a whole section, just write: None`

		`@@ -44,22 +34,13 @@`
		`having to look at additional files which can not be viewed in gerrit. It`
		`will also allow inline feedback on the diagram itself.`

		`- * If your specification proposes any changes to the Barbican REST API such`
		`- as changing parameters which can be returned or accepted, or even`
		`- the semantics of what happens when a client calls into the API, then`
		`- you should add the APIImpact flag to the commit message. Specifications with`
		`- the APIImpact flag can be found with the following query::`
		`-`
		`- https://review.openstack.org/#/q/status:open+project:openstack/barbican-specs+message:apiimpact,n,z`
		`-`

		`Problem Description`
		`===================`

		`A detailed description of the problem:`

		`- * For a new feature this might be use cases. Ensure you are clear about the`
		`- actors in each use case: End User vs Deployer`
		`+ * For a new feature this might be use cases.`

		`* For a major reworking of something existing it would describe the`
		`problems in that feature that are being addressed.`
		`@@ -81,21 +62,19 @@`
		`have to be a full literature review, but it should demonstrate that thought has`
		`been put into why the proposed solution is an appropriate one.`

		`+ This could also include some previously rejected designs.`
		`+`
		`Data model impact`
		`-----------------`

		`- Changes which require modifications to the data model often have a wider impact`
		`- on the system. The community often has strong opinions on how the data model`
		`- should be evolved, from both a functional and performance perspective. It is`
		`- therefore important to capture and gain agreement as early as possible on any`
		`- proposed changes to the data model.`
		`-`
		`Questions which need to be addressed by this section include:`

		`* What new data objects and/or database schema changes is this going to`
		`require?`

		`- * What database migrations will accompany this change (if any)?`
		`+ * What database migrations will accompany this change (if any)? Will`
		`+ databasemigration scripts run automatically or have to be triggered`
		`+ by the operator?`

		`* How will the initial set of new data objects be generated? For example, if you`
		`need to take into account existing keys, or modify other existing data`
		`@@ -187,11 +166,10 @@`
		`Please specify any changes to notifications or auditing. Be that an extra notification,`
		`changes to an existing notification, or removing a notification.`

		`- Python and Command Line Client Impact`
		`- -------------------------------------`
		`+ Command Line Client Impact`
		`+ --------------------------`

		`- Please specify any changes to the python and command line clients (CLI). Consider`
		`- the OpenStack unified clients as well as the soon to be deprecated Barbican clients.`
		`+ Please specify any changes to the command line clients (CLI).`

		`Other end user impact`
		`---------------------`
		`@@ -227,6 +205,11 @@`
		`* Will the change include any locking, and if so what considerations are there`
		`on holding the lock?`

		`+ Cloning Impact`
		`+ --------------`
		`+`
		`+ Any impact on cloning?`
		`+`
		`Other deployer impact`
		`---------------------`

		`@@ -254,11 +237,7 @@`
		`Developer impact`
		`----------------`

		`- Discuss things that will affect other developers working on OpenStack,`
		`- such as:`
		`-`
		`- * If the blueprint proposes a change to the driver API, discussion of how`
		`- other hypervisors would implement the feature is required.`
		`+ Discuss things that will affect other developers working on Dogtag,`


		`Implementation`
		`@@ -274,10 +253,10 @@`
		`primary author and contact.`

		`Primary assignee:`
		`- <launchpad-id or None>`
		`+ <fedora-id or None>`

		`Other contributors:`
		`- <launchpad-id or None>`
		`+ <fedora-id or None>`

		`Work Items`
		`----------`
		`@@ -290,25 +269,17 @@`
		`Dependencies`
		`============`

		`- * Include specific references to specs and/or blueprints in nova, or in other`
		`- projects, that this one either depends on or is related to.`
		`-`
		`- * If this requires functionality of another project that is not currently used`
		`- by Nova (such as the glance v2 API when we previously only required v1),`
		`- document that fact.`
		`+ * Include specific references to other design docs or features that this one either`
		`+ depends on or is related to.`

		`- * Does this feature require any new library dependencies or code otherwise not`
		`- included in OpenStack? Or does it depend on a specific version of library?`
		`+ * Are there any new package or library dependencies?`


		`Testing`
		`=======`

		`Please discuss how the change will be tested. We especially want to know what`
		`- tempest tests will be added. It is assumed that unit test coverage will be`
		`- added so that doesn't need to be mentioned explicitly, but discussion of why`
		`- you think unit tests are sufficient and we don't need to add more tempest`
		`- tests would need to be included.`
		`+ functional and unit tests will be added.`

		`Is this untestable in gate given current limitations (specific hardware /`
		`software configurations available)? If so, are there mitigation plans (3rd`
		`@@ -318,9 +289,8 @@`
		`Documentation Impact`
		`====================`

		`- What is the impact on the docs team of this change? Some changes might require`
		`- donating resources to the docs team to have the documentation updated. Don't`
		`- repeat details discussed above, but please reference them here.`
		`+ What is the impact on the docs of this change? Specifically, which docs`
		`+ and man pages need to be modified?`


		`References`
		`@@ -332,11 +302,10 @@`

		`* Links to mailing list or IRC discussions`

		`- * Links to notes from a summit session`
		`+ * Links to notes from a design session`

		`* Links to relevant research, if appropriate`

		`- * Related specifications as appropriate (e.g. if it's an EC2 thing, link the`
		`- EC2 docs)`
		`+ * Related specifications as appropriate.`

		`* Anything else you feel it is worthwhile to refer to`

no initial comment

vakwetu commented 8 years ago

This is the KRA ACL proposal ready for initial review.

edewata commented on line 38 of specs/10.3/kra-projects.rst 8 years ago

The path should be /kra/rest/keyrequests/{id}?action=approve

edewata commented on line 36 of specs/10.3/kra-projects.rst 8 years ago

The path should be /kra/rest/keyrequests/retrieve.

edewata commented on line 41 of specs/10.3/kra-projects.rst 8 years ago

a password

edewata commented on line 42 of specs/10.3/kra-projects.rst 8 years ago

/kra/rest/keys/{id}

edewata commented on line 72 of specs/10.3/kra-projects.rst 8 years ago

This sentence needs to be clarified.

edewata commented on line 88 of specs/10.3/kra-projects.rst 8 years ago

To avoid confusion "project" should be called "tag".

edewata commented on line 105 of specs/10.3/kra-projects.rst 8 years ago

This is a bit confusing. Probably it should be clarified that "escrow agent" is not a KRA agent. Alternatively we can call it "escrow officer".

edewata commented on line 397 of specs/10.3/kra-projects.rst 8 years ago

/keys/{key_id}/retrieve

edewata commented on line 120 of specs/10.3/kra-projects.rst 8 years ago

Does this mean we will no longer use pkidbuser, at least for KRA?

edewata commented on line 306 of specs/10.3/kra-projects.rst 8 years ago

Does the KRA admin have full access to the ACI in all projects? Or should there be project-specific admins that can manage project-specific ACI? Or should this task be delegated to project-specific admins?

edewata commented on line 317 of specs/10.3/kra-projects.rst 8 years ago

If we're going to support project-specific admin/agent, this interface is too generic, it allows the project-specific admin/agent to create an ACI for any project.

ftweedal commented on line 241 of specs/10.3/kra-projects.rst 8 years ago

Do these values have DN schema? We may need to set up referint for them (especially tag objects).

ftweedal commented on line 410 of specs/10.3/kra-projects.rst 8 years ago

404 seems more appropriate.

ftweedal commented on line 457 of specs/10.3/kra-projects.rst 8 years ago

Is there an immediate use case for modifying the CLI to support GSS-API, given that Barbican and IPA are the drivers?

ftweedal commented on line 541 of specs/10.3/kra-projects.rst 8 years ago

typo: documeNtation

ftweedal commented on line 511 of specs/10.3/kra-projects.rst 8 years ago

ftweedal :)

jmagne commented on line 118 of specs/10.3/kra-projects.rst 8 years ago

Could you elaborate as to what is the alternative to the simplifying assumption? What are we simplifying from.

jmagne commented on line 140 of specs/10.3/kra-projects.rst 8 years ago

Just curious as to what the agents would write to these records that are say owned by a regular user?

jmagne commented on line 205 of specs/10.3/kra-projects.rst 8 years ago

I am assuming that the user U0 is some kind of special user that is tasked with referencing the proper tag and come up with a list of users allowed to see his secret?

If this were just a dead simple user that wants to archive his secret, will he have to set all these fields? Apologies if I missed that part.

edewata commented on line 134 of specs/10.3/kra-projects.rst 8 years ago

The "tag" terminology is a little bit too generic/confusing. It might be better to use "project" like originally proposed. However, instead of defining just the permission, a "project" should define a set users, roles, and the resources (i.e. secrets).

The permission to the secrets can be determined by static ACIs and attributes defined in the secret itself.

There should be a REST interface to manage "projects" too. Basically a "project" can be considered as "light-weight KRA".

edewata commented on line 140 of specs/10.3/kra-projects.rst 8 years ago

If we use static ACI at top-level entries, the ACI can be added automatically when KRA is installed or when a project is created. A project can optionally have a default escrow officer.

edewata commented on line 159 of specs/10.3/kra-projects.rst 8 years ago

In IPA a vault can be owned by multiple owners, so the secret must be owned by multiple owners too.

edewata commented on line 159 of specs/10.3/kra-projects.rst 8 years ago

We can also add an "escrowOfficers" attribute to store non-default escrow officers (e.g. department-specific officers).

edewata commented on line 182 of specs/10.3/kra-projects.rst 8 years ago

The IPA tag/project should be created automatically when KRA is installed in IPA. The IPA admin later can add a global escrow officer for all IPA secrets. Alternatively, the IPA admin can add an escrow officer to a specific group to manage secrets belonging to the group.

edewata commented on line 185 of specs/10.3/kra-projects.rst 8 years ago

Defining a new ACL is too low-level and error-prone. Permissions can be defined using static/global ACLs and other attributes as described in lines #134 & #182.

edewata commented on line 193 of specs/10.3/kra-projects.rst 8 years ago

Since tag is global in KRA, the user might pick a wrong tag and accidentally exposes the secret to people in a different project:

$ ipa vault-add test --tag sales_secrets (whose sales dept?)

IPA should create all vaults with "ipa" project automatically. This should automatically grant IPA default escrow officer access to all IPA secrets.

To create group-specific escrow officer, IPA might need to provide new commands, for example:

$ ipa vault-group-add sales --escrow-officer-group "cn=Escrow Officers"

$ ipa vault-add test --group sales

The vault group only exists in IPA so it's not possible to incorrectly pick a group from another project.

edewata commented on line 159 of specs/10.3/kra-projects.rst 8 years ago

We can also add a "groups" attribute to store the groups this vault belongs to as described in line #193. The "groups" attribute will automatically grant group-specific escrow officers access to this secret.

edewata commented on line 210 of specs/10.3/kra-projects.rst 8 years ago

Similar to line #182, Barbican should create all vaults with "barbican" project.

edewata commented on line 306 of specs/10.3/kra-projects.rst 8 years ago

Constructing a correct database-level ACI is not trivial, so ideally ACIs should be static and few so it can be reviewed easily. Allowing dynamic ACI, even if it's limited to KRA admins, is risky.

If this were application-level ACI, it is fine if we want to provide a REST interface for it.

vakwetu commented on line 120 of specs/10.3/kra-projects.rst 8 years ago

Yes. The usual method of accessing the database only through
a single dbuser would not be used in these cases. Eventually, it will likely go away.

vakwetu commented on line 118 of specs/10.3/kra-projects.rst 8 years ago

The simplifying assumption is perhaps a clarification of my understanding. One basic change here is that we are getting
user and group information from an external authentication
source -- in this case, most likely - the IPA database.

I was imagining a situation where multiple authentication sources were present -- what happens if uid=admin is defined in both the KRA and IPA databases? In this case, there is no problem because the users map to different DNs.

The important point is that identities provided to us by GSSAPI are unique.

vakwetu commented on line 134 of specs/10.3/kra-projects.rst 8 years ago

What you describe is my initial understanding of how a project should be constituted. I'll add this to the alternatives section below.

nkinder mentioned though that it scales and performs better to have static tags that can be attached to secrets, rather than per-secret ACIs. So the idea is:

We have users defined by our identity provider (IPA) or internal db.
We have groups defined by our identity provider (IPA) or internal db.
We have ACIs that are defined at the top level which reference users/groups/tags.
Secrets are tagged.

In this model, ACIs represent the fundamental relationship of users, groups and secrets (as mediated through tags)

In the model you propose, projects represent the fundamental relationship between secrets, users and groups.

edewata commented on line 22 of specs/10.3/kra-projects.rst 8 years ago

Need to clarify that GSSAPI will only be used between IPA and PKI, but not between PKI and DS, although IPA is already using GSSAPI to communicate to DS directly.

edewata commented on line 126 of specs/10.3/kra-projects.rst 8 years ago

Can we call this "permission"? "Tag" is too generic and what it really does is granting permissions.

cfu commented on line 126 of specs/10.3/kra-projects.rst 8 years ago

I actually think "Tag" is more appropriate between the two. If "Tag" means some other things that could confuse anyone, words like "Label", "World", "scope" etc. to differentiate the realm or scope of the relevance could be used.

cfu commented on line 140 of specs/10.3/kra-projects.rst 8 years ago

If this is going to be a field that requires external management, then perhaps the "owner" field should be outside of the CS system. And perhaps change this field to be "creator" instead, a single value field that is populated when the record was first created.

cfu commented on line 178 of specs/10.3/kra-projects.rst 8 years ago

I actually prefer this one instead of special casing in the other method.

cfu commented on line 212 of specs/10.3/kra-projects.rst 8 years ago

It is probably fine to have metadata put in the key record at the time of creation, as long as no further management needed after the creation.

cfu commented on line 224 of specs/10.3/kra-projects.rst 8 years ago

I don't think non-CS role users should go into the KRA database. The day-to-day management of non-CS users should be kept out of the core CS.

cfu commented on line 233 of specs/10.3/kra-projects.rst 8 years ago

yes

cfu commented on line 276 of specs/10.3/kra-projects.rst 8 years ago

I was hoping that tags are static. Again, I'm hoping to keep day-to-day management of these out of the CS authorities..
Could the tag be static, and you have another external acl to specify whether an app has to a specific tag or not?

cfu commented on line 316 of specs/10.3/kra-projects.rst 8 years ago

yes. Overall, I believe that any application specific components, e.g. authentication and authorization are best to be implemented with plugin framework;
To maximize the flexibility of a product, its best to keep application-specific code/data outside of the core (non-plugin) areas. That's why I am making the suggestions that I have made as far for this design.

vakwetu commented on line 22 of specs/10.3/kra-projects.rst 8 years ago

will do.

vakwetu commented on line 126 of specs/10.3/kra-projects.rst 8 years ago

I think "tag" is more appropriate too. We could use "Label" if that is less confusing. We are labeling or tagging a secret to be of a specific type, so that we know how to apply permissions rules to it.

tag != permission
tag => (implies) set of permissions

What other use of "tag" are we trying to disambiguate against?

vakwetu commented on line 178 of specs/10.3/kra-projects.rst 8 years ago

It does make things cleaner, although there are migration considerations here. We don't want to disable existing customer's access to their secrets if a migration script failed to run.

Most likely, what we'll end up doing is having a migration script that adds the special tag, and then, on completion, sets a config flag that disables the special casing.

vakwetu commented on line 212 of specs/10.3/kra-projects.rst 8 years ago

Because the metadata is user-defined, I don't think we can enforce that it will not change. IPA, for example, will store the vault_secret_id here, and while that does not currently change, it seems unreasonable for us to require them to create a brand new secret and remove the old one in order to change it.

This is just defining a user-defined metadata field -- why does it have to be immutable?

vakwetu commented on line 224 of specs/10.3/kra-projects.rst 8 years ago

Eventually, barbican users will be defined in an IPA database and the barbican-dogtag-plugin will use kerberos/GSSAPI to talk with Dogtag. There is a lot of work needed to get there though.

In the interim and because it is possible to deploy the KRA with Barbican outside of IPA -- the simplest possible scenario to promote adoption -- we need to add the user to the KRA DB.

Note that we now need to consider CS as just another (albeit important) application that is using the KRA. If we have CS users, why not barbican users?

vakwetu commented on line 276 of specs/10.3/kra-projects.rst 8 years ago

Consider that several applications need to use the KRA to store secrets. Right now we have three -- CS, IPA Vault and Barbican.

Each application needs to contact the KRA administrator to:
a) register a plugin for authz
b) register tag(s) that map to that authz plugin

This must be done in co-ordination with the KRA administrator to ensure that the apps do not use the same tag.

This is just adding an interface that can be used by KRA admins to do this task, rather than having to go to the console (which we are trying to deprecate, remember?). It also allows apps to be added post-install possibly without server restart.

vakwetu commented on line 276 of specs/10.3/kra-projects.rst 8 years ago

We don't expect this to be a daily occurrence. We do expect though, that this should be made easy for the admin to do.

vakwetu commented on line 316 of specs/10.3/kra-projects.rst 8 years ago

Exactly. But tags are the way we associate authz plugins with specific keys. We need to manage those just as we need to manage which authz plugins are registered.

You could say that adding and mapping a tag is part of registering an authz plugin.

vakwetu commented on line 140 of specs/10.3/kra-projects.rst 8 years ago

I'm ok with this suggestion. If IPA or another app wants to have multiple "owners", then they can -- and in fact do -- keep track of it. Endi?

edewata commented on line 126 of specs/10.3/kra-projects.rst 8 years ago

The concern is if there's no well-defined usage people might use tags for things other than permission. When that happens it could interfere with how the permission works, and it would be harder to separate permission tags and non-permission tags later.

edewata commented on line 140 of specs/10.3/kra-projects.rst 8 years ago

Since we won't be using GSSAPI between PKI and DS, there is actually no need to have an owner/creator field in the DS since all secrets will only be accessed by pkidbuser. If we plan to have users other than pkidbuser to access the secrets, then it would make sense to have owner(s)/creator field with an ACL that grants certain permission.

edewata commented on line 140 of specs/10.3/kra-projects.rst 8 years ago

Also, since we won't be using GSSAPI between PKI and DS, there is no need to store tags in the DS either. The PKI server can utilize an authorization plugin to check with IPA if the user has access to certain secrets (which can be determined by IPA vault ownership/membership).