Initial commit

Author: dalibot

CHANGELOG

@@ -0,0 +1,3 @@
+Version 0.3 (beta), released 2015-01-22
+  - initial release
+

LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2012-2015, BRGM
+
+permission to use, copy, modify, and distribute this software and its
+documentation for any purpose, without fee, and without a written agreement
+is hereby granted, provided that the above copyright notice and this paragraph
+and the following two paragraphs appear in all copies.
+
+IN NO EVENT SHALL THE BRGM BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
+SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS,
+ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
+THE MAGISTRAT DER STADT WIEN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.
+
+THE BRGM SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE
+BRGM HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS,
+OR MODIFICATIONS.

Makefile

@@ -0,0 +1,8 @@
+#MODULES = external_file
+EXTENSION = external_file
+DATA = external_file--0.2.sql
+DOCS = README.external_file
+
+PG_CONFIG = pg_config
+PGXS := $(shell $(PG_CONFIG) --pgxs)
+include $(PGXS)

README.external_file

@@ -0,0 +1,132 @@
+External file access extension
+==============================
+
+Allow access to "external files" from PostgreSQL server file systems.
+This extension is only a "secure version" of the server side lo_* functions.
+
+1. Installation requirements
+============================
+PostgreSQL 9.1 or better are required.
+User with PostgreSQL superuser role for creating extension.
+
+2. Installation
+===============
+external_file has been written as a PostgreSQL extension and uses the Extension
+Building Infrastructure "PGXS".
+
+You will need PostgreSQL headers and PGXS installed (if your PostgreSQL was
+installed with packages, install the development package).
+
+Get/Unpack the source code in a fresh directory Then the software installation
+should be as simple as
+
+  $ make (In these version do nothing)
+  $ make install
+
+To install the extension in a database, connect as superuser and
+
+  CREATE EXTENSION external_file;
+
+By default all objects of the extension are created in the external_file schema.
+If you want to change the schema name you must edit the external_file.control
+file. Note that this schema must not be writable by normal user to not allow
+bypassing of the search path set with the security definer.
+
+
+When using schema with extension, it's better to include this schema in the
+default search_path. For example:
+
+	ALTER DATABASE <mydb> SET search_path="$user",public,external_file;
+
+Also you can restrict USAGE grant on external_file schema to specific user and
+change the default search path at user level too.
+
+	GRANT USAGE ON SCHEMA external_file TO <username>;
+
+Please refer to the PostgreSQL documentation for more information.
+
+
+3. Usage
+========
+External file are accessed using two values, an alias for the path of the
+directory where the file is, and the file name.
+
+So, first, alias must be defined for the path. This definition is performed
+using the "directories" table. For security reason, only superuser can insert,
+update, delete directory definition. It's possible, with GRANT command, to
+change this but it's NOT recommended.
+
+Example:
+
+  INSERT INTO directories(directory_name,directory_path) VALUES ('temporary','/tmp/');
+
+ATTENTION:
+ * the path must use the terminal separator!
+ * the system user running PostgreSQL server (generally postgres) must have the
+   system rights to read and/or write files
+ * the filename don't include any / or \ character for security reason
+
+Second, rights for user and/or role are defined using the "directory_access"
+table.
+
+Example:
+
+  INSERT INTO directory_roles(directory_name,directory_role,directory_read,directory_write) VALUES ('temporary','a_role',true,false);
+
+Now standard user can use external files.
+
+Example:
+
+  -- Store a new external file blahblah.txt into the directory
+  SELECT writeEfile('\x48656c6c6f2c0a0a596f75206172652072656164696e67206120746578742066696c652e0a0a526567617264732c0a', ('temporary', 'blahblah.txt'));
+
+	ls -la /tmp/blahblah.txt 
+	-rw-r--r-- 1 postgres postgres 47 janv. 22 19:16 /tmp/blahblah.txt
+
+  -- Create a table taht will use external files
+  CREATE TABLE efile_test ( id smallint primary key, the_file efile);
+  -- Insert a row to access the external file called blahblah.txt
+  INSERT INTO efile_test VALUES (1,('temporary','blahblah.txt'));
+  -- Assuming user has right to read, and the file exists
+  SELECT id, readefile(the_file) FROM efile_test;
+  -- Make a physical copy of the external file assuming user has right to read AND write
+  SELECT copyefile(('temporary','blahblah.txt'),('temporary','copy_blahblah.txt'));
+  INSERT INTO efile_test VALUES (2,('temporary','copy_blahblah.txt'));
+
+	ls /tmp/*blahblah.txt
+	-rw-r--r-- 1 postgres postgres 47 janv. 22 19:16 /tmp/blahblah.txt
+	-rw-r--r-- 1 postgres postgres 47 janv. 22 19:24 /tmp/copy_blahblah.txt
+
+  file=# SELECT id, readefile(the_file) FROM efile_test;
+   id |                                            readefile                                             
+  ----+--------------------------------------------------------------------------------------------------
+    1 | \x48656c6c6f2c0a0a596f75206172652072656164696e67206120746578742066696c652e0a0a526567617264732c0a
+    2 | \x48656c6c6f2c0a0a596f75206172652072656164696e67206120746578742066696c652e0a0a526567617264732c0a
+  (2 lines)
+ 
+
+4. Function reference
+=====================
+
+readEfile(e_file in efile) returns bytea
+  copy the external file into a bytea.
+  Error will be generated if something wrong.
+
+writeEfile(buffer in bytea, e_file in efile) returns void
+  copy a bytea into a external file.
+  Error will be generated if something wrong.
+
+copyEfile(src in efile, dest in efile) returns void
+  duplicate file defined by src into file dest
+  Error will be generated if something wrong.
+
+getEfilePath(e_file efile, need_read in boolean, need_write in boolean) returns text
+  giving an efile and booleans, one for read and one for write need, return the
+  full path for the file, otherwise an error is generated 
+  useful to check if session user has access to this external file
+
+5. License
+==========
+  Author Dominique Legendre
+  Copyright (c) 2012-2015 Brgm - All rights reserved.
+

TODO

@@ -0,0 +1,5 @@
+This is a list of things that should be done.
+Help is welcome!
+
+- Support to remove external files
+	CREATE OR REPLACE FUNCTION removeEfile(e_file efile) RETURNS void ...

external_file--0.2.sql

@@ -0,0 +1,152 @@
+-- External files extension for PostgreSQL
+-- Author Dominique Legendre
+-- Copyright (c) 2012-2015 Brgm - All rights reserved.
+
+-- complain if script is sourced in psql, rather than via CREATE EXTENSION
+\echo Use "CREATE EXTENSION external_file" to load this file. \quit
+
+
+CREATE TABLE directories (
+	directory_name name NOT NULL PRIMARY KEY,
+	directory_path text NOT NULL
+);
+
+REVOKE ALL ON directories FROM PUBLIC;
+GRANT SELECT ON directories TO PUBLIC;
+
+CREATE TABLE directory_roles (
+	directory_name name REFERENCES directories(directory_name) ON DELETE CASCADE ON UPDATE CASCADE,
+	directory_role name,
+	directory_read boolean NOT NULL,
+	directory_write boolean NOT NULL,
+	PRIMARY KEY (directory_name,directory_role)
+);
+
+REVOKE ALL ON directory_roles FROM PUBLIC;
+GRANT SELECT ON directory_roles TO PUBLIC;
+
+-- Include tables into pg_dump
+SELECT pg_catalog.pg_extension_config_dump('directories', '');
+SELECT pg_catalog.pg_extension_config_dump('directory_roles', '');
+
+
+CREATE TYPE efile AS (
+	directory name,
+	filename varchar(256)
+);
+
+REVOKE ALL ON TYPE efile FROM PUBLIC;
+GRANT USAGE ON TYPE efile TO PUBLIC;
+
+
+CREATE OR REPLACE FUNCTION getEfilePath(e_file efile, need_read boolean, need_write boolean)
+  RETURNS text
+AS $$
+DECLARE
+  p_path text;
+  r record;
+  read_enable boolean := false;
+  write_enable boolean := false;
+BEGIN
+  IF coalesce(e_file.filename,'')='' THEN
+    RAISE EXCEPTION 'Filename is empty.';
+  END IF;
+  IF e_file.filename ~ '(\\|/)' THEN
+	RAISE EXCEPTION '/ or \ are forbiden inside filename';
+  END IF;
+  SELECT directory_path INTO p_path FROM directories WHERE directory_name= e_file.directory;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'Directory % don''t exist.',e_file.directory;
+  END IF;
+  FOR r IN 
+    (SELECT directory_role,directory_read,directory_write FROM directory_roles WHERE directory_name= e_file.directory) LOOP
+	IF pg_has_role(session_user,r.directory_role,'USAGE') THEN
+		IF r.directory_read THEN
+			read_enable := true;
+		END IF;
+		IF r.directory_write THEN
+			write_enable := true;
+		END IF;
+	END IF;
+  END LOOP;
+  IF (need_read AND NOT read_enable) OR (need_write AND NOT write_enable) THEN
+    RAISE EXCEPTION 'Missing right for this directory: %' ,e_file.directory;
+  END IF;  
+  p_path := p_path|| e_file.filename;
+  RETURN p_path;
+END;
+$$
+LANGUAGE PLPGSQL STABLE SECURITY DEFINER SET search_path = @extschema@, pg_temp;
+
+
+CREATE OR REPLACE FUNCTION writeEfile(buffer bytea, e_file efile)
+  RETURNS void
+AS $$
+DECLARE
+  l_oid oid;
+  lfd integer;
+  lsize integer;
+BEGIN
+  l_oid := lo_create(0);
+  lfd := lo_open(l_oid,131072); --0x00020000 write mode
+  lsize := lowrite(lfd,buffer);
+  PERFORM lo_close(lfd);
+  PERFORM lo_export(l_oid,getEfilePath(e_file,false,true));
+  PERFORM lo_unlink(l_oid);
+END;
+$$ LANGUAGE PLPGSQL SECURITY DEFINER SET search_path = @extschema@, pg_temp;
+
+
+CREATE OR REPLACE FUNCTION readEfile(e_file efile, p_result OUT bytea)
+AS $$
+DECLARE
+  l_oid oid;
+  r record;
+BEGIN
+  p_result := '';
+  SELECT lo_import(getEfilePath(e_file,true,false)) INTO l_oid;
+  FOR r IN ( SELECT data 
+             FROM pg_largeobject 
+             WHERE loid = l_oid 
+             ORDER BY pageno ) LOOP
+    p_result = p_result || r.data;
+  END LOOP;
+  PERFORM lo_unlink(l_oid);
+END;
+$$
+LANGUAGE PLPGSQL SECURITY DEFINER SET search_path = @extschema@, pg_temp;
+
+
+CREATE OR REPLACE FUNCTION copyEfile(src efile, dest efile)
+  RETURNS void
+AS $$
+DECLARE
+  l_oid oid;
+BEGIN
+  SELECT lo_import(getEfilePath(src,true,false)) INTO l_oid;
+  PERFORM lo_export(l_oid,getEfilePath(dest,false,true));
+  PERFORM lo_unlink(l_oid);
+END;
+$$
+LANGUAGE PLPGSQL SECURITY DEFINER SET search_path = @extschema@, pg_temp;
+
+CREATE OR REPLACE FUNCTION efile_check_role()
+  RETURNS trigger
+AS $$
+BEGIN
+  PERFORM *  from pg_roles where rolname = NEW.directory_role;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'role % must exists', NEW.directory_role;
+    RETURN NULL;
+  END IF;
+  RETURN NEW;
+END;
+$$
+LANGUAGE PLPGSQL;
+
+CREATE TRIGGER trg_efile_check_role
+    BEFORE UPDATE OR INSERT ON directory_roles
+    FOR EACH ROW
+    EXECUTE PROCEDURE efile_check_role();
+
+

external_file.control

@@ -0,0 +1,6 @@
+comment = 'functions to read or write files from postgresql server filesystems'
+default_version = '0.2'
+encoding = 'utf8'
+relocatable = false
+superuser = true
+schema = external_file