The Crudge RT0 Browser

Launch Crudge Now

Intro

Crudge is a browser for credentials implementing the RT0 logic used by ABAC. The credentials are visualized as a directed graph where principals and roles/attributes are nodes in the graph and credentials are edges. If a principal has an attribute (can act in a role) there is a path through the directed graph from principal to attribute (role).

Crudge uses the same visualizations for roles that ​our description of ABAC for ​TIED uses. ​That description is a good starting point the visualizations and ABAC.

Crudge allows a user to visualize an ABAC proof or explore a policy. One can make queries against the policy and save all or parts of the policy. It can be used to create credentials and principals, that interoperate with the rest of ABAC. It can be used as a simple management interface for small systems using ABAC.

Running Crudge

Crudge is available as a webstart download. If you have java installed you should be able to run crudge by opening the URL http://abac.deterlab.net/java/crudge.jnlp. The various jar files are self-signed by the ISI ABAC team; if you're unwilling to trust self signed web start code you will have to download the jars separately and run them locally.

If you need java, you can get it at ​Oracle's Java site. A source repository will be available shortly.

Crudge makes use of the jabac library as well as the ​bouncycastle cryptographic libraries and ​Jung graph framework. All the relevant jar files are downloaded transparently from the webstart link above.

Using Crudge

This section describes navigating crudge. We describe the screens, how to manipulate credentials, and how to load and save credential sets. If everything seems intuitive to you, feel free to treat this tutorial as a reference.

Crudge Screens

When you first run crudge, you will be presented with a split screen like the one below.

The left side of the screen holds the worldviews. These are the views of credentials controlled by a given principal, and currently there is one worldview with all credentials visible. Because there are no credentials loaded, there are none displayed. The text entry box is used to restrict the view. When a principal name is entered, only those credentials controlled by that principal are shown. Multiple views can be shown simultaneously. We describe how to manipulate worldviews below.

On the right is the results of the current query, which is used to test if a given principal has a given attribute/role. The role is entered in the left text box and the principal in the right. If the query is successful, the query success icon turns into a green smiling face; a failed query shows the red "X". Queries are discussed in more detail below.

These input and output areas are summarized as:

Viewing a Graph

A credential graph represents a view of a set of ABAC credentials, for example the credentials that make up a proof or a policy. There are several ways to load a proof (described in more detail below), but to see the basics load an example set of credentials from http://abac.deterlab.net/examples/rockets_intersection.zip . Select "Open a URL" from the File menu and type http://abac.deterlab.net/examples/rockets_intersection.zip into the dialog box and hit return. (You can also get the dialog box by typing Ctrl-U).

A set of credentials will appear layed out roughly as a tree. You will probably need to move the boxes around a bit to see the structure. You can move a vertex by putting the pointer on it, holding down the left mouse button and dragging the box. You can pan around the space by putting the pointer on the background, holding the left button and dragging the whole frame. With a little moving you should see something like the image below.

This set of credentials represents the policy of a company called Acme that is in the business of selling armaments to fictional characters. There are four roles displayed and two principals. The principals are the two blue circles labelled "Coyote" and "Batman". The green rectangles are simple roles assigned by two principals not depicted ("Acme" and "WarnerBros"). A simple role is controlled by the principal to the left of the dot in the rectangle. Acme controls Acme.preferred_customer. WarnerBros controls WarnerBros.character.

The red rectangle represents an intersection role, which is the logical conjunction of the two roles separated by the ampersand, in this case Acme.preferred_customer and WarnerBros.character. A principal has an intersection role if it also has all of the individual roles. When the prerequisites for an intersection role are met by a principal, crudge connects the principal to the intersection role with a dotted line. In this example, Coyote has edges to both Acme.preferred_customer and WarnerBros.character, so it has a connection to the red role.

The solid lines represent credentials, the dotted lines represent deductions. This graph captures the idea that Acme will allow characters that are both its preferred customers and WarnerBros characters to buy rockets.

There is another kind of role, a linking role, that is described in more detail in the ​ABAC description referenced above.

Running A Query

The paths through this simple graph are easily traced by eye, but the query interface can be used to find the relevant paths through more tangled graphs. We demonstrate the query interface on the graph loaded above.

If a user enters Acme.buy_rockets in the leftmost query box and Coyote in the other and hits enter, that requests a proof that Coyote has the Acme.buy_rockets role. After that request is made (by hitting return) the query pane displays the following:

The query pane shows the smiling face icon and the part of the graph containing the path from Coyote to Acme.buy_rockets. The credential graph encodes the idea that to buy rockets from Acme, a principal must be a preferred customer of Acme (the Acme.preferred_customer role) and be a WarnerBros character (the WarnerBros.character role). The Coyote meets both conditions, but Batman meets only one in this example.

To see that Batman cannot buy rockets enter Acme.buy_rockets in the leftmost query box and Coyote in the other and hit enter. The pane will show an empty query with the red "X".

While Batman cannot buy rockets, he is a preferred customer, demonstrated by this query:

Working With Worldviews

Worldviews filter the role space to show what one principal would see or have to specify in a given scenario. Show how to apply worldviews to the example above. With the same example loaded, change the view layout to tabbed views by selecting "Tab Mode" under the View menu. In Tab Mode, either the current query or the views of the credentials are shown, and the tabs at the top can switch between them. After switching to tab mode, the screen looks like:

That is the single global view of the credentials. Add another view by choosing Add Worldview from the View menu (or hitting Ctrl-A), and the screen will split horizontally into two views. Type Acme into the text box on the lower view and you will see this:

The lower view shows only credentials controlled by the Acme principal. The red role depends on a role outside Acme's control (WarnerBros.character), so in the Acme view, the derived (dotted) connection for the Coyote to the red role cannot be deduced.

Worldviews are simply filtered views of all the known credentials, and you may add as many as you need.

Editing Credential Graphs

Editing credential graphs is fairly straightforward. When editing, crudge creates any missing but implied roles and principals, and credentials can be assigned by drawing arcs between nodes. For example, clear the current credentials by choosing "New" from the "File" menu, and then left click on the empty graph. A menu with an "Add Vertex" entry will appear. Entering "test.a & test.b" and hit enter, will cause 4 nodes to appear in the graph (after a short wait).

To get all the nodes in sight, they may need to be moved by dragging them with the left mouse button

A fair amount has happened. First because the vertex requested depended on two other roles, test.a and test.b, those roles were also created. In order to create those roles, a principal named test was needed to assign them, so crudge also created that principal. That principal has private and public keys known to crudge, and it can generate credentials issued by test.

To see that, add a second principal "Bob" by left clicking on the background and choosing "Add Vertex" again, and type Bob in. This creates a new principal, Bob, including generating his keys. Now hold down the shift key, press the left mouse button on Bob and drag the arrow this action creates over to the "test.a" role (the green rectangle).

In addition to drawing the arc from Bob to test.a, crudge has generated an ABAC credential, signed by test, that assigns the test.a role to Bob. If the principal has been loaded from a file or URL (see below) and crudge does not know the principal's private key, it will add a red arc to the graph. That arc will be included in query responses and create implied edges, but it cannot be saved, as crudge does not have the information to create the credential.

Now Connect Bob to the test.b role.

Again, crudge has created a credential for this arc (assigning test.b to Bob) and a dashed line has been added from Bob to the "test.a & test.b" role. Because Bob holds both these credentials, Bob has any of the roles predicated on the pair.

To delete an arc, put the mouse pointer over it, and choose "Delete Edge" from the menu (that choice will only appear if the pointer is directly on the edge). When you delete one of these edges, the credential is destroyed and the dashed arc disappears.

You can delete principals in a similar manner.

Node position does not matter, but you are free to move nodes around by dragging them, and the mouse wheel zooms in and out.

Vertex Types

When you create a new role by adding a vertex, there are 4 kinds of inputs that create different roles:

• A single name with no dots or ampersands - Bob
  • Creates a principal (blue circle). If the principal did not exist, a new certificate and key pair are created
• A single name with a single dot - Bob.role
  • Creates a simple role (green rectangle) that the principal before the dot can assign. If no such principal exists, it is created as if the principal name had been typed directly.
• A single name with two dots - Bob.linker.linked
  • Creates a linking role (red rectangle) that the principal before the first dot can indirectly assign. If the linking role does not exist (the role before the last dot) it is created as above.
• More than one of the above, linked by ampersands (&) - Bob.a & Bob.b
  • Creates an intersection role (red rectangle). If any of the roles are missing they are created as above.

Incoming edges to the red roles can only be created by crudge deducing them, but outgoing edges are allowed and useful. You cannot assign a principal the Bob.a & Bob.b role, but if you assign a principal both Bob.a and Bob.b, crudge fills in the edge as above.

Edge Types

Edges in a graph represent the following credentials and implications:

• Solid black edge
  • A signed credential exists for this edge.
  • Users can create these by holding the shift key down, pressing the left mouse button and dragging the arrow from one node to another.
• Solid red edge
  • This edge represents a credential, but crudge does not have enough information (e.g. a private key) to create it. The credential cannot be saved other than to an .rt0 file. Those files are described below.
  • Users can create these by holding the shift key down, pressing the left mouse button and dragging the arrow from one node to another.
• Light blue edge
  • Edge selected for inclusion in a subgraph
  • Users can select edges by clicking on them with the left mouse button. Multiple edges can be selected by holding down Ctrl while clicking
  • Users can use the "select all edges" button to select all edges from a successful query.
• Dashed black edge
  • This is a deduced edge. It connects a principal to an intersection or linking role.
  • Users cannot create these directly, but crudge will deduce them.

Loading Credential Graphs

Crudge can load ABAC information from several different file formats:

• Individual X.509 certificates that contain either principals (in PEM format) or ABAC credentials (in DER format)
• A directory containing X.509 certificates that contain either principals (in PEM format) or ABAC credentials (in DER format)
• A zip file of X.509 certificates that contain either principals (in PEM format) or ABAC credentials (in DER format)
• An rt0 file that includes only a description of the credentials, but no principal keys or credentials

The first three are pretty straightforward. The certificates that comprise a real policy or proof can be loaded from those formats and viewed and manipulated directly in crudge. Note that if the principal key pairs are not included, or are not accessible, crudge will not be able to create new certificates signed by those principals. Such credentials can still be reasoned about, but will be drawn in red to indicate that they cannot be exported.

The rt0 format is for simple debugging and testing. It consists of lines of the format:

Principal.role0 <-- Principal
Principal.role1 <-- Principal.role0
Principal.role2 <-- Principal.role11.role2
Principal.role3 <-- Principal.role11 & Principal.role2

The "Principal" and "rolen" in that description can be replaced with any named that do not contain dots or ampersands. Rt0 format is a textual encoding of RT0 rules.

To load any of these from the local file system, choose "Open File" or "Append File" from the File menu and choose the file or directory name. Append file does not clear the existing credentials from the displayed graph. If a file is appended that has the same principal name as one in the current graph, but that principal has a different keypair, crudge will assign the new principal a different name in the current display.

Zip files and rt0 files can also be loaded from URLs. The "Open URL" and Append URL" choices in the File menu accomplish this.

If a principal has been loaded from one source without its key pair, the key pair can be loaded using "Load Keys" from the "File" menu. Crudge can find the principal bound to the same key in memory. Note that this cannot be used to assign a key pair to a principal created by crudge.

Saving Credential Graphs

Crudge can save credential graphs either in a zip file containing the relevant credentials or in rt0 files for debugging. Rt0 files do not contain any cryptographic information and cannot directly specify proofs or policies. Zip files can be used to provide policies or proofs.

To save the entire credential graph, choose "Save" from the "File" menu and pick the save file name from the chooser. That chooser will look like this:

If the name ends in .zip or .rt0 that format will be used. If neither of these are chosen, or the user wants to force a format, the pull-down menu in the "Format" section of the file chooser can be used (it it displaying "Use suffix" in the image above).

Below that pull down menu are two check boxes that control extra information to be saved in the zip file. If "Include Private Keys" is selected, the identity certificates of the principals will include their private keys. This means that holders of the zip file will be able to generate new credentials from those principals. This is a feature if you are generating principals to act under the policy you are exporting, but a bug if you believe your are exporting a proof. It is off by default.

Unless "Include All Identities" is checked, only identities necessary to validate the credentials are included in the output. This means that principals who only have attributes assigned to them are not included. If this box is checked, identity certificates for those principals are included as well.

Neither of those check boxes are relevant to .rt0 files, because they contain no cryptographic material.

Saving Subgraphs

It is often convenient to save only some edges from a graph, either to use for a proof or as the set of credentials placed at a given player in the system. Crudge supports this by allowing users to select edges and save the credentials backing those edges (and relevant principals) to the same file formats described above.

There are two ways to select an edge: clicking on the edge (and holding Ctrl down to select multiple edges, clicking on each, not holding down the button), or using the "Select all edges" button in the query pane to select the edges in the valid query.

Once the edges have been selected, using the "Save subgraph" menu entry will save the subgraph, with the same choices of format and content as for a full graph.

Conclusion

That should be enough to get you started using crudge. If you have further questions contact us.