From 87ab326e99c0c6b556bfff54a6e4e9bd09faa495 Mon Sep 17 00:00:00 2001 Message-Id: <87ab326e99c0c6b556bfff54a6e4e9bd09faa495.1377873638.git.jdenemar@redhat.com> From: "Daniel P. Berrange" Date: Tue, 13 Aug 2013 11:38:26 +0100 Subject: [PATCH] Add info about access control checks into API reference For https://bugzilla.redhat.com/show_bug.cgi?id=700443 So that app developers / admins know what access control checks are performed for each API, this patch extends the API docs generator to include details of the ACLs for each. The gendispatch.pl script is extended so that it generates a simple XML describing ACL rules, eg. ... ... The newapi.xsl template loads the XML files containing the ACL rules and generates a short block of HTML for each API describing the parameter checks and return value filters (if any). Signed-off-by: Daniel P. Berrange (cherry picked from commit 664ab2801dfcb8e72fc4408cc50c279bf74e47a2) --- .gitignore | 3 +++ docs/libvirt.css | 14 +++++++++++ docs/newapi.xsl | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++ src/Makefile.am | 22 ++++++++++++++-- src/rpc/gendispatch.pl | 59 ++++++++++++++++++++++++++++++++++++++++--- 5 files changed, 160 insertions(+), 6 deletions(-) diff --git a/docs/libvirt.css b/docs/libvirt.css index 8a00d12..ed67b2f 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -477,3 +477,17 @@ dl.variablelist > dt { dl.variablelist > dt:after { content: ": "; } + +table.acl { + margin: 1em; + border-spacing: 0px; + border: 1px solid #ccc; +} + +table.acl tr, table.acl td { + padding: 0.3em; +} + +table.acl thead { + background: #ddd; +} diff --git a/docs/newapi.xsl b/docs/newapi.xsl index d5b210e..58f12eb 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -29,6 +29,69 @@ html ../ + + + + + + + + + + + + + + +
Access control parameter checks
+ + + + + + + + + +
ObjectPermissionCondition
+ + +
Access control return value filters
+ + + + + + + + +
ObjectPermission
+ + + + + + + + + + + + + - + + + + + + + + + + + + + @@ -553,6 +616,11 @@ +
+ + + +
diff --git a/src/Makefile.am b/src/Makefile.am index 12ca204..8c6f068 100644 --- a/src/Makefile.am +++ b/src/Makefile.am @@ -826,6 +826,11 @@ ACCESS_DRIVER_SYM_FILES = \ libvirt_access_qemu.syms \ libvirt_access_lxc.syms +ACCESS_DRIVER_API_FILES = \ + libvirt_access.xml \ + libvirt_access_qemu.xml \ + libvirt_access_lxc.xml + ACCESS_DRIVER_SOURCES = \ access/viraccessperm.h access/viraccessperm.c \ access/viraccessmanager.h access/viraccessmanager.c \ @@ -1492,8 +1497,8 @@ EXTRA_DIST += $(ACCESS_DRIVER_POLKIT_SOURCES) endif -BUILT_SOURCES += $(ACCESS_DRIVER_GENERATED) -CLEANFILES += $(ACCESS_DRIVER_GENERATED) +BUILT_SOURCES += $(ACCESS_DRIVER_GENERATED) $(ACCESS_DRIVER_API_FILES) +CLEANFILES += $(ACCESS_DRIVER_GENERATED) $(ACCESS_DRIVER_API_FILES) libvirt_access.syms: $(srcdir)/rpc/gendispatch.pl \ $(REMOTE_PROTOCOL) Makefile.am @@ -1508,6 +1513,19 @@ libvirt_access_lxc.syms: $(srcdir)/rpc/gendispatch.pl \ $(AM_V_GEN)$(PERL) -w $(srcdir)/rpc/gendispatch.pl --mode=aclsym \ lxc LXC $(LXC_PROTOCOL) > $@ +libvirt_access.xml: $(srcdir)/rpc/gendispatch.pl \ + $(REMOTE_PROTOCOL) Makefile.am + $(AM_V_GEN)$(PERL) -w $(srcdir)/rpc/gendispatch.pl --mode=aclapi \ + remote REMOTE $(REMOTE_PROTOCOL) > $@ +libvirt_access_qemu.xml: $(srcdir)/rpc/gendispatch.pl \ + $(QEMU_PROTOCOL) Makefile.am + $(AM_V_GEN)$(PERL) -w $(srcdir)/rpc/gendispatch.pl --mode=aclapi \ + qemu QEMU $(QEMU_PROTOCOL) > $@ +libvirt_access_lxc.xml: $(srcdir)/rpc/gendispatch.pl \ + $(LXC_PROTOCOL) Makefile.am + $(AM_V_GEN)$(PERL) -w $(srcdir)/rpc/gendispatch.pl --mode=aclapi \ + lxc LXC $(LXC_PROTOCOL) > $@ + $(srcdir)/access/viraccessapicheck.h: $(srcdir)/rpc/gendispatch.pl \ $(REMOTE_PROTOCOL) Makefile.am $(AM_V_GEN)$(PERL) -w $(srcdir)/rpc/gendispatch.pl --mode=aclheader \ diff --git a/src/rpc/gendispatch.pl b/src/rpc/gendispatch.pl index 8f41771..ac0c7ab 100755 --- a/src/rpc/gendispatch.pl +++ b/src/rpc/gendispatch.pl @@ -41,8 +41,8 @@ my $res = GetOptions("mode=s" => \$mode); die "cannot parse command line options" unless $res; die "unknown mode '$mode', expecting 'client', 'server', " . - "'aclheader', 'aclbody', 'aclsym' or 'debug'" - unless $mode =~ /^(client|server|aclheader|aclbody|aclsym|debug)$/; + "'aclheader', 'aclbody', 'aclsym', 'aclapi' or 'debug'" + unless $mode =~ /^(client|server|aclheader|aclbody|aclsym|aclapi|debug)$/; my $structprefix = shift or die "missing struct prefix argument"; my $procprefix = shift or die "missing procedure prefix argument"; @@ -351,6 +351,13 @@ if ($mode eq "aclsym") { # Automatically generated by gendispatch.pl. # Do not edit this file. Any changes you make will be lost. __EOF__ +} elsif ($mode eq "aclapi") { + print <<__EOF__; + +__EOF__ } else { print <<__EOF__; /* Automatically generated by gendispatch.pl. @@ -1641,7 +1648,8 @@ elsif ($mode eq "client") { } } elsif ($mode eq "aclheader" || $mode eq "aclbody" || - $mode eq "aclsym") { + $mode eq "aclsym" || + $mode eq "aclapi") { my %generate = map { $_ => 1 } @autogen; my @keys = keys %calls; @@ -1667,6 +1675,7 @@ elsif ($mode eq "client") { foreach my $hdr (@headers) { print "#include \"$hdr\"\n"; } + print "\n"; } elsif ($mode eq "aclbody") { my $header = shift; print "#include \n"; @@ -1676,8 +1685,12 @@ elsif ($mode eq "client") { print "#include \"virerror.h\"\n"; print "\n"; print "#define VIR_FROM_THIS VIR_FROM_ACCESS\n"; + print "\n"; + } elsif ($mode eq "aclapi") { + print "\n"; + } else { + print "\n"; } - print "\n"; foreach (@keys) { my $call = $calls{$_}; @@ -1699,6 +1712,8 @@ elsif ($mode eq "client") { print $apiname . "CheckACL;\n"; } print $apiname . "EnsureACL;\n"; + } elsif ($mode eq "aclapi") { + &generate_aclapi($call); } else { &generate_acl($call, $call->{acl}, "Ensure"); if (defined $call->{aclfilter}) { @@ -1835,5 +1850,41 @@ elsif ($mode eq "client") { print "}\n\n"; } } + + sub generate_aclapi { + my $call = shift; + + my $apiname = "vir" . $call->{ProcName}; + if ($structprefix eq "qemu") { + $apiname =~ s/virDomain/virDomainQemu/; + } elsif ($structprefix eq "lxc") { + $apiname =~ s/virDomain/virDomainLxc/; + } + + print " \n"; + + my $acl = $call->{acl}; + foreach (@{$acl}) { + my @bits = split /:/; + print " \n"; + } + + my $aclfilter = $call->{aclfilter}; + foreach (@{$aclfilter}) { + my @bits = split /:/; + print " \n"; + } + + print " \n"; + } + + } + + if ($mode eq "aclapi") { + print "\n"; } } -- 1.8.3.2