From 31918a7bb701791f367c252bb411276d018fdf96 Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Oct 08 2015 15:36:09 +0000 Subject: [PATCH 1/9] initial commit for alee_branch --- diff --git a/NOTE.txt b/NOTE.txt new file mode 100644 index 0000000..868ca76 --- /dev/null +++ b/NOTE.txt @@ -0,0 +1,9 @@ +This branch is only for alee to use. + +Unfortunately there is a bug/missing feature in Pagure +whereby the owner of the main repo cannot clone his own +repo. This makes it difficult for the owner (me) to make +commits that are reviewable. + +Sucky, but until that gets fixed -- alee will submit +pull requests from this branch to master. From 920b32b787806b9e10ddcd4be9da32061b4867dd Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Oct 08 2015 15:40:32 +0000 Subject: [PATCH 2/9] Test commit from alee_branch --- diff --git a/specs/template.rst b/specs/template.rst index 663627d..529091e 100644 --- a/specs/template.rst +++ b/specs/template.rst @@ -8,13 +8,10 @@ Example Spec - The title of your blueprint ========================================== -Include the URL of your launchpad blueprint: +Most of this stuff is very openstack specific. I'll put in something +that reflects what we currently have -- based on mharmsen's page. -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. From beff0dff3e048e57547c457647d03bf74218d23a Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Oct 08 2015 15:44:16 +0000 Subject: [PATCH 3/9] Remove extra file --- diff --git a/NOTE.txt b/NOTE.txt deleted file mode 100644 index 868ca76..0000000 --- a/NOTE.txt +++ /dev/null @@ -1,9 +0,0 @@ -This branch is only for alee to use. - -Unfortunately there is a bug/missing feature in Pagure -whereby the owner of the main repo cannot clone his own -repo. This makes it difficult for the owner (me) to make -commits that are reviewable. - -Sucky, but until that gets fixed -- alee will submit -pull requests from this branch to master. From f195c20dfc1e2017edb15c256e1ff7f6131100ea Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Nov 04 2015 17:28:08 +0000 Subject: [PATCH 4/9] Modified template to make it more in line with Dogtag --- diff --git a/specs/template.rst b/specs/template.rst index 529091e..9c8c10a 100644 --- a/specs/template.rst +++ b/specs/template.rst @@ -4,12 +4,9 @@ http://creativecommons.org/licenses/by/3.0/legalcode -========================================== -Example Spec - The title of your blueprint -========================================== - -Most of this stuff is very openstack specific. I'll put in something -that reflects what we currently have -- based on mharmsen's page. +================================================== + Example Design Doc - The title of your Design Doc +================================================== http://pki.fedoraproject.org/wiki/PKI_Feature_Template @@ -22,10 +19,6 @@ Some notes about using this template: * 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 @@ -41,22 +34,13 @@ Some notes about using this template: 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. @@ -78,21 +62,19 @@ What other ways could we do this thing? Why aren't we using those? This doesn't 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 @@ -184,11 +166,10 @@ Notifications & Audit Impact 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 --------------------- @@ -224,6 +205,11 @@ Examples of things to consider here include: * 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 --------------------- @@ -251,11 +237,7 @@ that have not already been mentioned, such as: 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 @@ -271,10 +253,10 @@ If more than one person is working on the implementation, please designate the primary author and contact. Primary assignee: - + Other contributors: - + Work Items ---------- @@ -287,25 +269,17 @@ but we're mostly trying to understand the timeline for implementation. 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 @@ -315,9 +289,8 @@ party testing, gate enhancements, etc). 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 @@ -329,11 +302,10 @@ references are unavailable. Examples of what you could include are: * 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 From 48d3fcb76da5dbe5b01ef1a566310b44c2773232 Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Nov 04 2015 21:52:29 +0000 Subject: [PATCH 5/9] Initial edit for KRA changes --- diff --git a/specs/10.3/kra-projects.rst b/specs/10.3/kra-projects.rst new file mode 100644 index 0000000..721ad6b --- /dev/null +++ b/specs/10.3/kra-projects.rst @@ -0,0 +1,395 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +============= + KRA Projects +============= + +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. + +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 credential (owner? project?) + 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 the "project". + +* When the first secret in a escrowed vault is stored, IPA makes calls to + create a new project (possibly named after the vault itself), and to add + the escrow agent to that project. + +* Secrets are stored with the owner and project. The project will be + passed in as a parameter to POST /keys. + +* When the key is retrieved, the retriever's credentials are obtained + through GSSAPI and a principal is provided by the Tomcat realm. + +* The secret is retrieved if the retriever is the secret's owner, or if + a) a project is defined for the secret + b) the retriever is a member of that project + +* The encrypted vault encryption key is stored by the agent using direct + archival under his own credentials. Only the agent can retrieve that + secret. + +* Note that the retriever is NOT an agent. This means that the retriever + does not have access to any other secrets, or have permissions to do the + types of things that an agent can do. + +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 have no owner or project. 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 any secrets that have either an owner or a project. + +* 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 part of a project to which the agent belongs. + The escrow agents are not agents on the CS subsystem, so they have no + permissions other than to retrieve the specified secrets. + +* The Barbican escrow agent will likewise no longer be an agent. Instead, + all Barbican secrets will be archived using the direct archive method + and the owner will be set to the barbican escrow agent. + +We'll consider migration scenarios below. + +Proposed Change +=============== + +Here is where you cover the change you propose to make in detail. How do you +propose to solve this problem? + +If this is one part of a larger effort make it clear where this piece ends. In +other words, what's the scope of this effort? + +Alternatives +------------ + +What other ways could we do this thing? Why aren't we using those? This doesn't +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 +----------------- + +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)? 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 + describe how that will work. + +REST API impact +--------------- + +Each API method which is either added or changed should have the following + +* Specification for the method + + * A description of what the method does suitable for use in + user documentation + + * Method type (POST/PUT/GET/DELETE) + + * Normal http response code(s) + + * Expected error http response code(s) + + * A description for each possible error code should be included + describing semantic errors which can cause it such as + inconsistent parameters supplied to the method, or when an + instance is not in an appropriate state for the request to + succeed. Errors caused by syntactic problems covered by the JSON + schema defintion do not need to be included. + + * URL for the resource + + * Parameters which can be passed via the url + + * JSON schema definition for the body data if allowed + + * JSON schema definition for the response data if any + +* Example use case including typical API samples for both data supplied + by the caller and the response + +* Discuss any policy changes, and discuss what things a deployer needs to + think about when defining their policy. + +Example JSON schema definitions can be found in the Nova tree +http://git.openstack.org/cgit/openstack/nova/tree/nova/api/openstack/compute/schemas/v3 + +Note that the schema should be defined as restrictively as +possible. Parameters which are required should be marked as such and +only under exceptional circumstances should additional parameters +which are not defined in the schema be permitted (eg +additionaProperties should be False). + +Reuse of existing predefined parameter types such as regexps for +passwords and user defined names is highly encouraged. + +Security impact +--------------- + +Describe any potential security impact on the system. Some of the items to +consider include: + +* Does this change touch sensitive data such as tokens, keys, or user data? + +* Does this change alter the API in a way that may impact security, such as + a new way to access sensitive information or a new way to login? + +* Does this change involve cryptography or hashing? + +* Does this change require the use of sudo or any elevated privileges? + +* Does this change involve using or parsing user-provided data? This could + be directly at the API level or indirectly such as changes to a cache layer. + +* Can this change enable a resource exhaustion attack, such as allowing a + single API interaction to consume significant server resources? Some examples + of this include launching subprocesses for each connection, or entity + expansion attacks in XML. + +* Does this change change the need for auditing in any way? + +For more detailed guidance, please see the OpenStack Security Guidelines as +a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These +guidelines are a work in progress and are designed to help you identify +security best practices. For further information, feel free to reach out +to the OpenStack Security Group at openstack-security@lists.openstack.org. + +Notifications & Audit Impact +---------------------------- + +Please specify any changes to notifications or auditing. Be that an extra notification, +changes to an existing notification, or removing a notification. + +Command Line Client Impact +-------------------------- + +Please specify any changes to the command line clients (CLI). + +Other end user impact +--------------------- + +Aside from the API, are there other ways a user will interact with this +feature? + +* Does this change have an impact on python-novaclient? What does the user + interface there look like? + +Performance Impact +------------------ + +Describe any potential performance impact on the system, for example +how often will new code be called, and is there a major change to the calling +pattern of existing code. + +Examples of things to consider here include: + +* A periodic task might look like a small addition but if it calls conductor or + another service the load is multiplied by the number of nodes in the system. + +* Scheduler filters get called once per host for every instance being created, + so any latency they introduce is linear with the size of the system. + +* A small change in a utility function or a commonly used decorator can have a + large impacts on performance. + +* Calls which result in a database queries (whether direct or via conductor) + can have a profound impact on performance when called in critical sections of + the code. + +* 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 +--------------------- + +Discuss things that will affect how you deploy and configure OpenStack +that have not already been mentioned, such as: + +* What config options are being added? Should they be more generic than + proposed (for example a flag that other hypervisor drivers might want to + implement as well)? Are the default values ones which will work well in + real deployments? + +* Is this a change that takes immediate effect after its merged, or is it + something that has to be explicitly enabled? + +* If this change is a new binary, how would it be deployed? + +* Please state anything that those doing continuous deployment, or those + upgrading from the previous release, need to be aware of. Also describe + any plans to deprecate configuration values or features. For example, if we + change the directory name that instances are stored in, how do we handle + instance directories created before the change landed? Do we move them? Do + we have a special case in the code? Do we assume that the operator will + recreate all the instances in their cloud? + +Developer impact +---------------- + +Discuss things that will affect other developers working on Dogtag, + + +Implementation +============== + +Assignee(s) +----------- + +Who is leading the writing of the code? Or is this a blueprint where you're +throwing it out there to see who picks it up? + +If more than one person is working on the implementation, please designate the +primary author and contact. + +Primary assignee: + + +Other contributors: + + +Work Items +---------- + +Work items or tasks -- break the feature up into the things that need to be +done to implement it. Those parts might end up being done by different people, +but we're mostly trying to understand the timeline for implementation. + + +Dependencies +============ + +* Include specific references to other design docs or features that this one either + depends on or is related to. + +* Are there any new package or library dependencies? + + +Testing +======= + +Please discuss how the change will be tested. We especially want to know what +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 +party testing, gate enhancements, etc). + + +Documentation Impact +==================== + +What is the impact on the docs of this change? Specifically, which docs +and man pages need to be modified? + + +References +========== + +Please add any useful references here. You are not required to have any +reference. Moreover, this specification should still make sense when your +references are unavailable. Examples of what you could include are: + +* Links to mailing list or IRC discussions + +* Links to notes from a design session + +* Links to relevant research, if appropriate + +* Related specifications as appropriate. + +* Anything else you feel it is worthwhile to refer to From 1dab3244ca08b69025c095f90025041310829f6e Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Nov 06 2015 19:02:52 +0000 Subject: [PATCH 6/9] KRA ACL proposal --- diff --git a/doc/source/index.rst b/doc/source/index.rst index be9d8b7..1c144a5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -28,6 +28,15 @@ Juno approved specs: specs/juno/* +10.3 approved specs: + +.. toctree:: + :glob: + :maxdepth: 1 + + specs/10.3/* + + ================== Indices and tables ================== diff --git a/specs/10.3/kra-projects.rst b/specs/10.3/kra-projects.rst new file mode 100644 index 0000000..dbf163f --- /dev/null +++ b/specs/10.3/kra-projects.rst @@ -0,0 +1,545 @@ +.. + 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. + +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 +=============== + +To make this problem more tractable, we need to make a simplifying +assumption. This assumption is that there is only one authentication +source in which users are groups are going to be stored, and therefore that +all identities for users will be unique. + +Access control will be achieved via ACLs that are enforced by the directory +server. Note that this is not the same as the ACLs that are defined +in the Dogtag application and enforced by the DirAclAuthz authorization +class. + +These access control rules will reference users and groups which are +either defined in the IPA database (which exists in the same instance as +the KRA internaldb) or in the KRA internaldb. This relies on the simplifying +assumption mentioned above. + +In addition, secrets will be tagged with user defined tags (like "ipa" +or "barbican" or "dept1_secrets"), which can be referenced by the ACL. +Interfaces to add and remove tags (which will be limited to KRA +administrators) will need to be added. Those interfaces are described below. + +An example of an ACL is shown below:: + + example of an ACL + more of the ACL + +Administration (adding/removing/modifying ACLs) will be restricted to +administrators. + +The following fields will be added to each secret: + +* tags - user defined label that can be used in ACLs. While creating or + removing tags is an adminstrative operation, permission to tag or + untag a secret will be permitted for the owner and members of the secret + by default. + +* members - this a list of users which can be modified by the secret's + owner. The permissions for these users will be defined by an ACL. + By default, members will be able to retrieve a secret. This field + is necessary because in IPA, vaults contain a field called members, + which can be modified by the regular user. + +* owner - This will be populated by Dogtag when the secret is stored + as the principal returned by the Tomcat realm. + +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. + + * Modifying the key request servlets to explicitly exclude those keys + which have an owner. + +* IPA vault: + + * The IPA administrator would define a tag for the secrets archived + by the organization's escrow officer group. Lets call it "sales_secrets" + for illustrative sake. + + * The IPA adninstrator would define an ACL that would permit the retrieval + and modification of the secret by escrow officer group EG0. + + * User U0 will create a secret corresponding to a vault using direct + archival, and will specify the members attribute to contain the + principals for U1, U2 and U3. The owner field will be populated + with the U0 principal by the Dogtag application. + + * User U0 would tag the secret for the vault with the tag + "sales_secrets". + + * When the secret is retrieved by the user U0 using direct access, + a default ACL (see the Database section below) will permit access as + U0 is the owner of the secret. + + * When a secret is retrieved by U1, U2 or U3, a default ACL will permit + access as any of these principals are on the members list. + + * When an escrow agent retrieves the secret by direct access, access is + permitted because of the ACL added by the IPA administrator above. + + * Otherwise, access is denied. + +* Barbican access: + + * When Barbican is configured to interact with the KRA, a KRA + administrator will create a "barbican-XXX" tag. + + * The adminstrator will also create a group of barbican agents in + IPA, as well as an ACL that permits barbican agents to retrieve + barbican tagged secrets. + + * When secrets are stored by the Barbican agents, they are tagged + with the relevant "Barbican-XXX" tag. + +Some examples: + +* 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. In this case, + IPA would create the secret using direct archival proxying UO's + credentials. + +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?) + +* member (which can be multi-valued) + +* tag (which can be multi-valued) + +The following default acis (or similar) will need to be added to the +ou=keyRepository, ou=kra, {rootSuffix} entry to: + +* Allow owners all permissions on their keyRecord objects. + +* Allow principals that match the member attribute to perform all operations + on the keyRecord object. + +Any ACIs corresponding to tags will need to be added post-install during +normal operation. + +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. + 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. + +An interface (completely restricted to KRA admins) is needed to +add ACIs. + +* Add or modify an ACI + + * Add an ACI for secrets. + In this case, we also use PUT because the acl is defined by a user + defined acl_id. If the ACL exists, then it is replaced. + + * PUT /kra/acls/{acl_id} + + * Returns 200 on success + + * Body of the request is a json blob containing the following: + + * target - DN to which the ACL should be applied + + * targetattr (defaults to "*") + + * targetfilter + + * version (defaults to "3.0") + + * permissions + + * userdn + + * userattr + + * groupdn + + * groupattr + + * Ideally we could end up doing some syntax checking of the constructed + ACI. This will create an ACI that looks something like this:: + + aci:(target={target})(targetattr={targetattr})(version={version}; + acl {acl_id}; allow ({permissions} + [userdn={userdn} userattr={userattr}; | + groupdn={groupdn} groupattr={groupattr};]) + + * Returns 400 error on syntax errors in adding the ACI to the DB or if + the target DN does not exist. + + * Request limited to KRA admins. + +* Remove ACI + + * Remove an ACI. + + * DEL /kra/acls/{foo} + + * Returns 204 on success + + * Returns 404 if the ACI does not exist + + * Request limited to KRA admins. + +* List ACIs: + + * GET /kra/acls?target={foo} + + * If target is undefined, return the top level of the key repository. + + * Request restricted to KRA admins. + +* Get ACI: + + * GET /kra/acls/{foo} + + * Request restricted to KRAadmins. + +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 + +* GET /keys/{key_id}/members - List members + +* PUT /keys/{key_id}/members/{member_id} - add a member to the secret. + +* DEL /keys/{key_id}/members/{member_id} - delete a member 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 a greater load on the database to compute and evaluate +ACI when secrets are stored and retrieved. This can be mitigated by +creating the relevant indexes - perhaps for certain tags. + +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 fweeedal + +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 From f6883776868fff15ea263ec9acac7d076cbff943 Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Nov 06 2015 19:06:42 +0000 Subject: [PATCH 7/9] KRA ACL proposal -- merges --- diff --git a/specs/10.3/kra-projects.rst b/specs/10.3/kra-projects.rst index dbf163f..721ad6b 100644 --- a/specs/10.3/kra-projects.rst +++ b/specs/10.3/kra-projects.rst @@ -4,9 +4,9 @@ http://creativecommons.org/licenses/by/3.0/legalcode -================================ - Refined permissions for the KRA -================================ +============= + KRA Projects +============= 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 @@ -34,12 +34,11 @@ 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 +* 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} + providing either apassword for a PKCS12 file or a symmetric key to wrap the + secret. This is GET /keys/{id} 1-Agent mediated retrieval: @@ -61,7 +60,7 @@ 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) +* Secret is stored in the KRA, along with the credential (owner? project?) and a key_id is returned. Direct Retrieval: @@ -70,29 +69,50 @@ Direct Retrieval: 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. + 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. +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. +access the user's secret. The proposed mechanism will be the "project". +* When the first secret in a escrowed vault is stored, IPA makes calls to + create a new project (possibly named after the vault itself), and to add + the escrow agent to that project. + +* Secrets are stored with the owner and project. The project will be + passed in as a parameter to POST /keys. + +* When the key is retrieved, the retriever's credentials are obtained + through GSSAPI and a principal is provided by the Tomcat realm. + +* The secret is retrieved if the retriever is the secret's owner, or if + a) a project is defined for the secret + b) the retriever is a member of that project + +* The encrypted vault encryption key is stored by the agent using direct + archival under his own credentials. Only the agent can retrieve that + secret. + +* Note that the retriever is NOT an agent. This means that the retriever + does not have access to any other secrets, or have permissions to do the + types of things that an agent can do. + 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. + These keys will have no owner or project. 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 any secrets that have either an owner or a project. * 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 @@ -100,404 +120,209 @@ end-state: * 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. + the owner or which are part of a project to which the agent belongs. + The escrow agents are not agents on the CS subsystem, so they have no + permissions other than to retrieve the specified secrets. -* 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. +* The Barbican escrow agent will likewise no longer be an agent. Instead, + all Barbican secrets will be archived using the direct archive method + and the owner will be set to the barbican escrow agent. + +We'll consider migration scenarios below. Proposed Change =============== -To make this problem more tractable, we need to make a simplifying -assumption. This assumption is that there is only one authentication -source in which users are groups are going to be stored, and therefore that -all identities for users will be unique. - -Access control will be achieved via ACLs that are enforced by the directory -server. Note that this is not the same as the ACLs that are defined -in the Dogtag application and enforced by the DirAclAuthz authorization -class. - -These access control rules will reference users and groups which are -either defined in the IPA database (which exists in the same instance as -the KRA internaldb) or in the KRA internaldb. This relies on the simplifying -assumption mentioned above. - -In addition, secrets will be tagged with user defined tags (like "ipa" -or "barbican" or "dept1_secrets"), which can be referenced by the ACL. -Interfaces to add and remove tags (which will be limited to KRA -administrators) will need to be added. Those interfaces are described below. - -An example of an ACL is shown below:: - - example of an ACL - more of the ACL - -Administration (adding/removing/modifying ACLs) will be restricted to -administrators. - -The following fields will be added to each secret: - -* tags - user defined label that can be used in ACLs. While creating or - removing tags is an adminstrative operation, permission to tag or - untag a secret will be permitted for the owner and members of the secret - by default. - -* members - this a list of users which can be modified by the secret's - owner. The permissions for these users will be defined by an ACL. - By default, members will be able to retrieve a secret. This field - is necessary because in IPA, vaults contain a field called members, - which can be modified by the regular user. - -* owner - This will be populated by Dogtag when the secret is stored - as the principal returned by the Tomcat realm. - -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. - - * Modifying the key request servlets to explicitly exclude those keys - which have an owner. - -* IPA vault: - - * The IPA administrator would define a tag for the secrets archived - by the organization's escrow officer group. Lets call it "sales_secrets" - for illustrative sake. - - * The IPA adninstrator would define an ACL that would permit the retrieval - and modification of the secret by escrow officer group EG0. - - * User U0 will create a secret corresponding to a vault using direct - archival, and will specify the members attribute to contain the - principals for U1, U2 and U3. The owner field will be populated - with the U0 principal by the Dogtag application. - - * User U0 would tag the secret for the vault with the tag - "sales_secrets". - - * When the secret is retrieved by the user U0 using direct access, - a default ACL (see the Database section below) will permit access as - U0 is the owner of the secret. - - * When a secret is retrieved by U1, U2 or U3, a default ACL will permit - access as any of these principals are on the members list. - - * When an escrow agent retrieves the secret by direct access, access is - permitted because of the ACL added by the IPA administrator above. - - * Otherwise, access is denied. +Here is where you cover the change you propose to make in detail. How do you +propose to solve this problem? -* Barbican access: - - * When Barbican is configured to interact with the KRA, a KRA - administrator will create a "barbican-XXX" tag. - - * The adminstrator will also create a group of barbican agents in - IPA, as well as an ACL that permits barbican agents to retrieve - barbican tagged secrets. - - * When secrets are stored by the Barbican agents, they are tagged - with the relevant "Barbican-XXX" tag. - -Some examples: - -* 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. In this case, - IPA would create the secret using direct archival proxying UO's - credentials. +If this is one part of a larger effort make it clear where this piece ends. In +other words, what's the scope of this effort? Alternatives ------------ -None. +What other ways could we do this thing? Why aren't we using those? This doesn't +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 ----------------- -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?) - -* member (which can be multi-valued) +Questions which need to be addressed by this section include: -* tag (which can be multi-valued) +* What new data objects and/or database schema changes is this going to + require? -The following default acis (or similar) will need to be added to the -ou=keyRepository, ou=kra, {rootSuffix} entry to: +* What database migrations will accompany this change (if any)? Will + databasemigration scripts run automatically or have to be triggered + by the operator? -* Allow owners all permissions on their keyRecord objects. - -* Allow principals that match the member attribute to perform all operations - on the keyRecord object. - -Any ACIs corresponding to tags will need to be added post-install during -normal operation. - -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. +* 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 + describe how that will work. 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. - 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} +Each API method which is either added or changed should have the following - * Request can be run by anyone. +* Specification for the method -An interface (completely restricted to KRA admins) is needed to -add ACIs. + * A description of what the method does suitable for use in + user documentation -* Add or modify an ACI + * Method type (POST/PUT/GET/DELETE) - * Add an ACI for secrets. - In this case, we also use PUT because the acl is defined by a user - defined acl_id. If the ACL exists, then it is replaced. + * Normal http response code(s) - * PUT /kra/acls/{acl_id} + * Expected error http response code(s) - * Returns 200 on success + * A description for each possible error code should be included + describing semantic errors which can cause it such as + inconsistent parameters supplied to the method, or when an + instance is not in an appropriate state for the request to + succeed. Errors caused by syntactic problems covered by the JSON + schema defintion do not need to be included. - * Body of the request is a json blob containing the following: + * URL for the resource - * target - DN to which the ACL should be applied + * Parameters which can be passed via the url - * targetattr (defaults to "*") + * JSON schema definition for the body data if allowed - * targetfilter + * JSON schema definition for the response data if any - * version (defaults to "3.0") +* Example use case including typical API samples for both data supplied + by the caller and the response - * permissions +* Discuss any policy changes, and discuss what things a deployer needs to + think about when defining their policy. - * userdn +Example JSON schema definitions can be found in the Nova tree +http://git.openstack.org/cgit/openstack/nova/tree/nova/api/openstack/compute/schemas/v3 - * userattr +Note that the schema should be defined as restrictively as +possible. Parameters which are required should be marked as such and +only under exceptional circumstances should additional parameters +which are not defined in the schema be permitted (eg +additionaProperties should be False). - * groupdn +Reuse of existing predefined parameter types such as regexps for +passwords and user defined names is highly encouraged. - * groupattr - - * Ideally we could end up doing some syntax checking of the constructed - ACI. This will create an ACI that looks something like this:: - - aci:(target={target})(targetattr={targetattr})(version={version}; - acl {acl_id}; allow ({permissions} - [userdn={userdn} userattr={userattr}; | - groupdn={groupdn} groupattr={groupattr};]) - - * Returns 400 error on syntax errors in adding the ACI to the DB or if - the target DN does not exist. - - * Request limited to KRA admins. - -* Remove ACI - - * Remove an ACI. - - * DEL /kra/acls/{foo} - - * Returns 204 on success - - * Returns 404 if the ACI does not exist - - * Request limited to KRA admins. - -* List ACIs: - - * GET /kra/acls?target={foo} - - * If target is undefined, return the top level of the key repository. - - * Request restricted to KRA admins. - -* Get ACI: - - * GET /kra/acls/{foo} - - * Request restricted to KRAadmins. - -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. +Security impact +--------------- -* DEL /keys/{key_id}/tags/{tag_id} - delete a tag from the secret +Describe any potential security impact on the system. Some of the items to +consider include: -* GET /keys/{key_id}/members - List members +* Does this change touch sensitive data such as tokens, keys, or user data? -* PUT /keys/{key_id}/members/{member_id} - add a member to the secret. +* Does this change alter the API in a way that may impact security, such as + a new way to access sensitive information or a new way to login? -* DEL /keys/{key_id}/members/{member_id} - delete a member from the secret +* Does this change involve cryptography or hashing? -* POST /keys - archive a secret. Passes in a ResourceMessage. +* Does this change require the use of sudo or any elevated privileges? -Security impact ---------------- +* Does this change involve using or parsing user-provided data? This could + be directly at the API level or indirectly such as changes to a cache layer. -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. +* Can this change enable a resource exhaustion attack, such as allowing a + single API interaction to consume significant server resources? Some examples + of this include launching subprocesses for each connection, or entity + expansion attacks in XML. -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. +* Does this change change the need for auditing in any way? -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. +For more detailed guidance, please see the OpenStack Security Guidelines as +a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These +guidelines are a work in progress and are designed to help you identify +security best practices. For further information, feel free to reach out +to the OpenStack Security Group at openstack-security@lists.openstack.org. Notifications & Audit Impact ---------------------------- -We need to ensure that all the new interfaces are completely audited. +Please specify any changes to notifications or auditing. Be that an extra notification, +changes to an existing notification, or removing a notification. 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. +Please specify any changes to the command line clients (CLI). 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. - +Aside from the API, are there other ways a user will interact with this +feature? + +* Does this change have an impact on python-novaclient? What does the user + interface there look like? + Performance Impact ------------------ -There will be a greater load on the database to compute and evaluate -ACI when secrets are stored and retrieved. This can be mitigated by -creating the relevant indexes - perhaps for certain tags. +Describe any potential performance impact on the system, for example +how often will new code be called, and is there a major change to the calling +pattern of existing code. + +Examples of things to consider here include: + +* A periodic task might look like a small addition but if it calls conductor or + another service the load is multiplied by the number of nodes in the system. + +* Scheduler filters get called once per host for every instance being created, + so any latency they introduce is linear with the size of the system. + +* A small change in a utility function or a commonly used decorator can have a + large impacts on performance. + +* Calls which result in a database queries (whether direct or via conductor) + can have a profound impact on performance when called in critical sections of + the code. -On the other hand though, direct access makes the process simpler - -no more creating and acting on archival and retrieval requests. +* Will the change include any locking, and if so what considerations are there + on holding the lock? Cloning Impact -------------- -As ACIs are replicated across clones, there should be no impact on cloning. +Any impact on cloning? Other deployer impact --------------------- -TBA. +Discuss things that will affect how you deploy and configure OpenStack +that have not already been mentioned, such as: -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. +* What config options are being added? Should they be more generic than + proposed (for example a flag that other hypervisor drivers might want to + implement as well)? Are the default values ones which will work well in + real deployments? -Barbican is not yet widely deployed, and there are fewer changes here in -any case. +* Is this a change that takes immediate effect after its merged, or is it + something that has to be explicitly enabled? -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. +* If this change is a new binary, how would it be deployed? + +* Please state anything that those doing continuous deployment, or those + upgrading from the previous release, need to be aware of. Also describe + any plans to deprecate configuration values or features. For example, if we + change the directory name that instances are stored in, how do we handle + instance directories created before the change landed? Do we move them? Do + we have a special case in the code? Do we assume that the operator will + recreate all the instances in their cloud? Developer impact ---------------- -TBA during implementation. +Discuss things that will affect other developers working on Dogtag, + Implementation ============== @@ -505,41 +330,66 @@ Implementation Assignee(s) ----------- +Who is leading the writing of the code? Or is this a blueprint where you're +throwing it out there to see who picks it up? + +If more than one person is working on the implementation, please designate the +primary author and contact. + Primary assignee: - vakwetu or fweeedal + Other contributors: - edewata + Work Items ---------- -To be completed once the design has been approved. +Work items or tasks -- break the feature up into the things that need to be +done to implement it. Those parts might end up being done by different people, +but we're mostly trying to understand the timeline for implementation. + Dependencies ============ -* These changes require Dogtag being modified to accept GSSAPI authentication. - That design is being written by Fraser. +* Include specific references to other design docs or features that this one either + depends on or is related to. + +* Are there any new package or library dependencies? 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. +Please discuss how the change will be tested. We especially want to know what +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 +party testing, gate enhancements, etc). + 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. +What is the impact on the docs of this change? Specifically, which docs +and man pages need to be modified? + References ========== -None +Please add any useful references here. You are not required to have any +reference. Moreover, this specification should still make sense when your +references are unavailable. Examples of what you could include are: + +* Links to mailing list or IRC discussions + +* Links to notes from a design session + +* Links to relevant research, if appropriate + +* Related specifications as appropriate. + +* Anything else you feel it is worthwhile to refer to From fd2b2b488ebc558f5cf34e22acb89438c5174ff2 Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Nov 10 2015 15:24:21 +0000 Subject: [PATCH 8/9] KRA ACL proposal - remerge --- diff --git a/specs/10.3/kra-projects.rst b/specs/10.3/kra-projects.rst index 721ad6b..9e2604a 100644 --- a/specs/10.3/kra-projects.rst +++ b/specs/10.3/kra-projects.rst @@ -4,9 +4,9 @@ http://creativecommons.org/licenses/by/3.0/legalcode -============= - KRA Projects -============= +================================ + 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 @@ -34,11 +34,12 @@ 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 +* 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} + providing either apassword for a PKCS12 file or a symmetric key to wrap + the secret. This is GET /keys/{id} 1-Agent mediated retrieval: @@ -60,7 +61,7 @@ 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 credential (owner? project?) +* Secret is stored in the KRA, along with the principal (owner) and a key_id is returned. Direct Retrieval: @@ -69,50 +70,29 @@ Direct Retrieval: 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. + 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. +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 the "project". +access the user's secret. The proposed mechanism will be through tags and +ACLs. -* When the first secret in a escrowed vault is stored, IPA makes calls to - create a new project (possibly named after the vault itself), and to add - the escrow agent to that project. - -* Secrets are stored with the owner and project. The project will be - passed in as a parameter to POST /keys. - -* When the key is retrieved, the retriever's credentials are obtained - through GSSAPI and a principal is provided by the Tomcat realm. - -* The secret is retrieved if the retriever is the secret's owner, or if - a) a project is defined for the secret - b) the retriever is a member of that project - -* The encrypted vault encryption key is stored by the agent using direct - archival under his own credentials. Only the agent can retrieve that - secret. - -* Note that the retriever is NOT an agent. This means that the retriever - does not have access to any other secrets, or have permissions to do the - types of things that an agent can do. - 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 have no owner or project. 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 any secrets that have either an owner or a project. + 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 @@ -120,209 +100,405 @@ end-state: * 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 part of a project to which the agent belongs. - The escrow agents are not agents on the CS subsystem, so they have no - permissions other than to retrieve the specified secrets. + the owner or which are permitted through tags/ACLs to access the secret. -* The Barbican escrow agent will likewise no longer be an agent. Instead, - all Barbican secrets will be archived using the direct archive method - and the owner will be set to the barbican escrow agent. - -We'll consider migration scenarios below. +* 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 =============== -Here is where you cover the change you propose to make in detail. How do you -propose to solve this problem? +To make this problem more tractable, we need to make a simplifying +assumption. This assumption is that there is only one authentication +source in which users are groups are going to be stored, and therefore that +all identities for users will be unique. + +Access control will be achieved via ACLs that are enforced by the directory +server. Note that this is not the same as the ACLs that are defined +in the Dogtag application and enforced by the DirAclAuthz authorization +class. + +These access control rules will reference users and groups which are +either defined in the IPA database (which exists in the same instance as +the KRA internaldb) or in the KRA internaldb. This relies on the simplifying +assumption mentioned above. + +In addition, secrets will be tagged with user defined tags (like "ipa" +or "barbican" or "dept1_secrets"), which can be referenced by the ACL. +Interfaces to add and remove tags (which will be limited to KRA +administrators) will need to be added. Those interfaces are described below. + +An example of an ACL is shown below:: + + aci: (targetattr="*")(targetfilter=(&(objectClass=keyRecord)(tag=ipa))) + (version 3.0; acl "ipa-escrow-agent-access"; allow (read,search,write) + groupdn="ldap:///cn=Escrow Agents,ou=Groups,o=example.com";) + +Administration (adding/removing/modifying ACLs) will be restricted to +administrators. + +The following fields will be added to each secret: + +* tags - user defined label that can be used in ACLs. While creating or + removing tags is an adminstrative operation, permission to tag or + untag a secret will be permitted for the owner and members of the secret + by default. + +* members - this a list of users which can be modified by the secret's + owner. The permissions for these users will be defined by an ACL. + By default, members will be able to retrieve a secret. This field + is necessary because in IPA, vaults contain a field called members, + which can be modified by the regular user. + +* owner - This will be populated by Dogtag when the secret is stored + as the principal returned by the Tomcat realm. + +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. + + * Modifying the key request servlets to explicitly exclude those keys + which have an owner. + +* IPA vault: + + * The IPA administrator would define a tag for the secrets archived + by the organization's escrow officer group. Lets call it "sales_secrets" + for illustrative sake. + + * The IPA adninstrator would define an ACL that would permit the retrieval + and modification of the secret by escrow officer group EG0. + + * User U0 will create a secret corresponding to a vault using direct + archival, and will specify the members attribute to contain the + principals for U1, U2 and U3. The owner field will be populated + with the U0 principal by the Dogtag application. + + * User U0 would tag the secret for the vault with the tag + "sales_secrets". + + * When the secret is retrieved by the user U0 using direct access, + a default ACL (see the Database section below) will permit access as + U0 is the owner of the secret. + + * When a secret is retrieved by U1, U2 or U3, a default ACL will permit + access as any of these principals are on the members list. + + * When an escrow agent retrieves the secret by direct access, access is + permitted because of the ACL added by the IPA administrator above. + + * Otherwise, access is denied. -If this is one part of a larger effort make it clear where this piece ends. In -other words, what's the scope of this effort? +* Barbican access: + + * When Barbican is configured to interact with the KRA, a KRA + administrator will create a "barbican-XXX" tag. + + * The adminstrator will also create a group of barbican agents in + IPA, as well as an ACL that permits barbican agents to retrieve + barbican tagged secrets. + + * When secrets are stored by the Barbican agents, they are tagged + with the relevant "Barbican-XXX" tag. + +Some examples: + +* 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. In this case, + IPA would create the secret using direct archival proxying UO's + credentials. Alternatives ------------ -What other ways could we do this thing? Why aren't we using those? This doesn't -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. +None. Data model impact ----------------- -Questions which need to be addressed by this section include: +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?) + +* member (which can be multi-valued) -* What new data objects and/or database schema changes is this going to - require? +* tag (which can be multi-valued) -* What database migrations will accompany this change (if any)? Will - databasemigration scripts run automatically or have to be triggered - by the operator? +The following default acis (or similar) will need to be added to the +ou=keyRepository, ou=kra, {rootSuffix} entry to: -* 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 - describe how that will work. +* Allow owners all permissions on their keyRecord objects. + +* Allow principals that match the member attribute to perform all operations + on the keyRecord object. + +Any ACIs corresponding to tags will need to be added post-install during +normal operation. + +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 --------------- -Each API method which is either added or changed should have the following +An interface will need to be added to add and remove tags. -* Specification for the method +* Add or modify tags - * A description of what the method does suitable for use in - user documentation + * Add a tag to be used in ACIs for secrets. This tag is user defined. + 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. - * Method type (POST/PUT/GET/DELETE) + * PUT /kra/tags/{foo} - * Normal http response code(s) + * Returns 201 (Created) on success - * Expected error http response code(s) + * Returns 409 (Conflict) if the tag already exists. - * A description for each possible error code should be included - describing semantic errors which can cause it such as - inconsistent parameters supplied to the method, or when an - instance is not in an appropriate state for the request to - succeed. Errors caused by syntactic problems covered by the JSON - schema defintion do not need to be included. + * Body of the request is a json blob containing "description" - * URL for the resource + * Request limited to KRA admins. - * Parameters which can be passed via the url +* Remove tag - * JSON schema definition for the body data if allowed + * Remove a tag. This tag is user defined. - * JSON schema definition for the response data if any + * DEL /kra/tags/{foo} -* Example use case including typical API samples for both data supplied - by the caller and the response + * Returns 204 on success -* Discuss any policy changes, and discuss what things a deployer needs to - think about when defining their policy. + * Returns 404 if the ACI does not exist -Example JSON schema definitions can be found in the Nova tree -http://git.openstack.org/cgit/openstack/nova/tree/nova/api/openstack/compute/schemas/v3 + * Request limited to KRA admins. -Note that the schema should be defined as restrictively as -possible. Parameters which are required should be marked as such and -only under exceptional circumstances should additional parameters -which are not defined in the schema be permitted (eg -additionaProperties should be False). +* List tags: -Reuse of existing predefined parameter types such as regexps for -passwords and user defined names is highly encouraged. + * GET /kra/tags -Security impact ---------------- + * Request can be run by anyone. + +* Get tag: + + * GET /kra/tags/{foo} + + * Request can be run by anyone. + +An interface (completely restricted to KRA admins) is needed to +add ACIs. + +* Add or modify an ACI + + * Add an ACI for secrets. + In this case, we also use PUT because the acl is defined by a user + defined acl_id. If the ACL exists, then it is replaced. + + * PUT /kra/acls/{acl_id} + + * Returns 200 on success + + * Body of the request is a json blob containing the following: + + * target - DN to which the ACL should be applied + + * targetattr (defaults to "*") + + * targetfilter + + * version (defaults to "3.0") + + * permissions + + * userdn + + * userattr -Describe any potential security impact on the system. Some of the items to -consider include: + * groupdn -* Does this change touch sensitive data such as tokens, keys, or user data? + * groupattr -* Does this change alter the API in a way that may impact security, such as - a new way to access sensitive information or a new way to login? + * Ideally we could end up doing some syntax checking of the constructed + ACI. This will create an ACI that looks something like this:: -* Does this change involve cryptography or hashing? + aci:(target={target})(targetattr={targetattr})(version={version}; + acl {acl_id}; allow ({permissions} + [userdn={userdn} userattr={userattr}; | + groupdn={groupdn} groupattr={groupattr};]) -* Does this change require the use of sudo or any elevated privileges? + * Returns 400 error on syntax errors in adding the ACI to the DB or if + the target DN does not exist. -* Does this change involve using or parsing user-provided data? This could - be directly at the API level or indirectly such as changes to a cache layer. + * Request limited to KRA admins. -* Can this change enable a resource exhaustion attack, such as allowing a - single API interaction to consume significant server resources? Some examples - of this include launching subprocesses for each connection, or entity - expansion attacks in XML. +* Remove ACI -* Does this change change the need for auditing in any way? + * Remove an ACI. -For more detailed guidance, please see the OpenStack Security Guidelines as -a reference (https://wiki.openstack.org/wiki/Security/Guidelines). These -guidelines are a work in progress and are designed to help you identify -security best practices. For further information, feel free to reach out -to the OpenStack Security Group at openstack-security@lists.openstack.org. + * DEL /kra/acls/{foo} + + * Returns 204 on success + + * Returns 404 if the ACI does not exist + + * Request limited to KRA admins. + +* List ACIs: + + * GET /kra/acls?target={foo} + + * If target is undefined, return the top level of the key repository. + + * Request restricted to KRA admins. + +* Get ACI: + + * GET /kra/acls/{foo} + + * Request restricted to KRAadmins. + +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 + +* GET /keys/{key_id}/members - List members + +* PUT /keys/{key_id}/members/{member_id} - add a member to the secret. + +* DEL /keys/{key_id}/members/{member_id} - delete a member 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 ---------------------------- -Please specify any changes to notifications or auditing. Be that an extra notification, -changes to an existing notification, or removing a notification. +We need to ensure that all the new interfaces are completely audited. Command Line Client Impact -------------------------- -Please specify any changes to the command line clients (CLI). +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 --------------------- -Aside from the API, are there other ways a user will interact with this -feature? - -* Does this change have an impact on python-novaclient? What does the user - interface there look like? - +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 ------------------ -Describe any potential performance impact on the system, for example -how often will new code be called, and is there a major change to the calling -pattern of existing code. - -Examples of things to consider here include: - -* A periodic task might look like a small addition but if it calls conductor or - another service the load is multiplied by the number of nodes in the system. - -* Scheduler filters get called once per host for every instance being created, - so any latency they introduce is linear with the size of the system. - -* A small change in a utility function or a commonly used decorator can have a - large impacts on performance. - -* Calls which result in a database queries (whether direct or via conductor) - can have a profound impact on performance when called in critical sections of - the code. +There will be a greater load on the database to compute and evaluate +ACI when secrets are stored and retrieved. This can be mitigated by +creating the relevant indexes - perhaps for certain tags. -* Will the change include any locking, and if so what considerations are there - on holding the lock? +On the other hand though, direct access makes the process simpler - +no more creating and acting on archival and retrieval requests. Cloning Impact -------------- -Any impact on cloning? +As ACIs are replicated across clones, there should be no impact on cloning. Other deployer impact --------------------- -Discuss things that will affect how you deploy and configure OpenStack -that have not already been mentioned, such as: +TBA. -* What config options are being added? Should they be more generic than - proposed (for example a flag that other hypervisor drivers might want to - implement as well)? Are the default values ones which will work well in - real deployments? +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. -* Is this a change that takes immediate effect after its merged, or is it - something that has to be explicitly enabled? +Barbican is not yet widely deployed, and there are fewer changes here in +any case. -* If this change is a new binary, how would it be deployed? - -* Please state anything that those doing continuous deployment, or those - upgrading from the previous release, need to be aware of. Also describe - any plans to deprecate configuration values or features. For example, if we - change the directory name that instances are stored in, how do we handle - instance directories created before the change landed? Do we move them? Do - we have a special case in the code? Do we assume that the operator will - recreate all the instances in their cloud? +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 ---------------- -Discuss things that will affect other developers working on Dogtag, - +TBA during implementation. Implementation ============== @@ -330,66 +506,41 @@ Implementation Assignee(s) ----------- -Who is leading the writing of the code? Or is this a blueprint where you're -throwing it out there to see who picks it up? - -If more than one person is working on the implementation, please designate the -primary author and contact. - Primary assignee: - + vakwetu or fweeedal Other contributors: - + edewata Work Items ---------- -Work items or tasks -- break the feature up into the things that need to be -done to implement it. Those parts might end up being done by different people, -but we're mostly trying to understand the timeline for implementation. - +To be completed once the design has been approved. Dependencies ============ -* Include specific references to other design docs or features that this one either - depends on or is related to. - -* Are there any new package or library dependencies? +* These changes require Dogtag being modified to accept GSSAPI authentication. + That design is being written by Fraser. Testing ======= -Please discuss how the change will be tested. We especially want to know what -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 -party testing, gate enhancements, etc). - +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 ==================== -What is the impact on the docs of this change? Specifically, which docs -and man pages need to be modified? - +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 ========== -Please add any useful references here. You are not required to have any -reference. Moreover, this specification should still make sense when your -references are unavailable. Examples of what you could include are: - -* Links to mailing list or IRC discussions - -* Links to notes from a design session - -* Links to relevant research, if appropriate - -* Related specifications as appropriate. - -* Anything else you feel it is worthwhile to refer to +None From b529d02c36a96ac310ae893ec1880bee5935337f Mon Sep 17 00:00:00 2001 From: Ade Lee Date: Nov 16 2015 17:15:53 +0000 Subject: [PATCH 9/9] KRA ACL proposal after feedback from edewata, ftweedal and cfu. --- diff --git a/specs/10.3/kra-projects.rst b/specs/10.3/kra-projects.rst index 9e2604a..a021253 100644 --- a/specs/10.3/kra-projects.rst +++ b/specs/10.3/kra-projects.rst @@ -111,51 +111,57 @@ end-state: Proposed Change =============== -To make this problem more tractable, we need to make a simplifying -assumption. This assumption is that there is only one authentication -source in which users are groups are going to be stored, and therefore that -all identities for users will be unique. - -Access control will be achieved via ACLs that are enforced by the directory -server. Note that this is not the same as the ACLs that are defined -in the Dogtag application and enforced by the DirAclAuthz authorization -class. - -These access control rules will reference users and groups which are -either defined in the IPA database (which exists in the same instance as -the KRA internaldb) or in the KRA internaldb. This relies on the simplifying -assumption mentioned above. - -In addition, secrets will be tagged with user defined tags (like "ipa" -or "barbican" or "dept1_secrets"), which can be referenced by the ACL. -Interfaces to add and remove tags (which will be limited to KRA -administrators) will need to be added. Those interfaces are described below. - -An example of an ACL is shown below:: - - aci: (targetattr="*")(targetfilter=(&(objectClass=keyRecord)(tag=ipa))) - (version 3.0; acl "ipa-escrow-agent-access"; allow (read,search,write) - groupdn="ldap:///cn=Escrow Agents,ou=Groups,o=example.com";) +Authentication +-------------- -Administration (adding/removing/modifying ACLs) will be restricted to -administrators. +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. -The following fields will be added to each secret: +Tags +---- -* tags - user defined label that can be used in ACLs. While creating or - removing tags is an adminstrative operation, permission to tag or - untag a secret will be permitted for the owner and members of the secret - by default. +When a secret is stored, the following fields will be added to each secret: -* members - this a list of users which can be modified by the secret's - owner. The permissions for these users will be defined by an ACL. - By default, members will be able to retrieve a secret. This field - is necessary because in IPA, vaults contain a field called members, - which can be modified by the regular user. +* 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. + 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. + +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: @@ -171,57 +177,70 @@ satisfied using the mechanism above: that tag. * Modifying the key request servlets to explicitly exclude those keys - which have an owner. + which are tagged. * IPA vault: - * The IPA administrator would define a tag for the secrets archived - by the organization's escrow officer group. Lets call it "sales_secrets" - for illustrative sake. + 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. - * The IPA adninstrator would define an ACL that would permit the retrieval - and modification of the secret by escrow officer group EG0. + * During the IPA install, the KRA administrator would define a tag "ipa" + and register and configure the IPAAuthzPlugin. - * User U0 will create a secret corresponding to a vault using direct - archival, and will specify the members attribute to contain the - principals for U1, U2 and U3. The owner field will be populated - with the U0 principal by the Dogtag application. + * 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". - * User U0 would tag the secret for the vault with the tag - "sales_secrets". + * 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. - * When the secret is retrieved by the user U0 using direct access, - a default ACL (see the Database section below) will permit access as - U0 is the owner of the secret. - - * When a secret is retrieved by U1, U2 or U3, a default ACL will permit - access as any of these principals are on the members list. - - * When an escrow agent retrieves the secret by direct access, access is - permitted because of the ACL added by the IPA administrator above. + * 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). - * Otherwise, access is denied. + * Another way is to add a user defined metadata field to the the key record + 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-XXX" tag. + 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. - * The adminstrator will also create a group of barbican agents in - IPA, as well as an ACL that permits barbican agents to retrieve - barbican tagged secrets. + 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. - * When secrets are stored by the Barbican agents, they are tagged - with the relevant "Barbican-XXX" tag. + * 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. -Some examples: + * 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. -* 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. In this case, - IPA would create the secret using direct archival proxying UO's - credentials. + * 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 ------------ @@ -235,21 +254,13 @@ 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?) -* member (which can be multi-valued) - -* tag (which can be multi-valued) - -The following default acis (or similar) will need to be added to the -ou=keyRepository, ou=kra, {rootSuffix} entry to: - -* Allow owners all permissions on their keyRecord objects. - -* Allow principals that match the member attribute to perform all operations - on the keyRecord object. - -Any ACIs corresponding to tags will need to be added post-install during -normal operation. +* 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. @@ -300,81 +311,12 @@ An interface will need to be added to add and remove tags. * Request can be run by anyone. -An interface (completely restricted to KRA admins) is needed to -add ACIs. - -* Add or modify an ACI - - * Add an ACI for secrets. - In this case, we also use PUT because the acl is defined by a user - defined acl_id. If the ACL exists, then it is replaced. - - * PUT /kra/acls/{acl_id} - - * Returns 200 on success - - * Body of the request is a json blob containing the following: - - * target - DN to which the ACL should be applied - - * targetattr (defaults to "*") - - * targetfilter - - * version (defaults to "3.0") - - * permissions - - * userdn - - * userattr - - * groupdn - - * groupattr - - * Ideally we could end up doing some syntax checking of the constructed - ACI. This will create an ACI that looks something like this:: - - aci:(target={target})(targetattr={targetattr})(version={version}; - acl {acl_id}; allow ({permissions} - [userdn={userdn} userattr={userattr}; | - groupdn={groupdn} groupattr={groupattr};]) - - * Returns 400 error on syntax errors in adding the ACI to the DB or if - the target DN does not exist. - - * Request limited to KRA admins. - -* Remove ACI - - * Remove an ACI. - - * DEL /kra/acls/{foo} - - * Returns 204 on success - - * Returns 404 if the ACI does not exist - - * Request limited to KRA admins. - -* List ACIs: - - * GET /kra/acls?target={foo} - - * If target is undefined, return the top level of the key repository. - - * Request restricted to KRA admins. - -* Get ACI: - - * GET /kra/acls/{foo} - - * Request restricted to KRAadmins. +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. 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. +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 @@ -410,12 +352,6 @@ Operations to be added include: * DEL /keys/{key_id}/tags/{tag_id} - delete a tag from the secret -* GET /keys/{key_id}/members - List members - -* PUT /keys/{key_id}/members/{member_id} - add a member to the secret. - -* DEL /keys/{key_id}/members/{member_id} - delete a member from the secret - * POST /keys - archive a secret. Passes in a ResourceMessage. Security impact @@ -466,9 +402,9 @@ using either old or new clients with an updated server. Performance Impact ------------------ -There will be a greater load on the database to compute and evaluate -ACI when secrets are stored and retrieved. This can be mitigated by -creating the relevant indexes - perhaps for certain tags. +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. @@ -507,7 +443,7 @@ Assignee(s) ----------- Primary assignee: - vakwetu or fweeedal + vakwetu or ftweedal Other contributors: edewata