From 79936c4c419e602a824376a933661590e593a9c9 Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Sun, 29 Oct 2017 13:09:45 -0700 Subject: [PATCH] GUACAMOLE-96: Document semantics of voluntary attribute storage and guaranteed sanitization. --- .../org/apache/guacamole/net/auth/Connection.java | 13 +++++++++++-- .../apache/guacamole/net/auth/ConnectionGroup.java | 13 +++++++++++-- .../apache/guacamole/net/auth/SharingProfile.java | 11 ++++++++++- .../java/org/apache/guacamole/net/auth/User.java | 13 +++++++++++-- 4 files changed, 43 insertions(+), 7 deletions(-) diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/Connection.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/Connection.java index 85fd1680d..313d89e20 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/Connection.java +++ b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/Connection.java @@ -95,8 +95,17 @@ public interface Connection extends Identifiable, Connectable { /** * Sets the given attributes. If an attribute within the map is not - * supported, it will simply be dropped. Any attributes not within the - * given map will be left untouched. + * supported, it will simply be dropped. Any attributes not within the given + * map will be left untouched. Attributes which are not declared within + * getConnectionAttributes() of the associated UserContext MUST NOT be + * submitted, but other extensions may manipulate the declared attributes + * through decorate() and redecorate(). + * + * Implementations may optionally allow storage of unsupported attributes. + * Extensions which rely on other extensions to store their attribute + * values should verify that such storage is supported by first testing + * that the attribute value is retrievable via getAttributes() after being + * set. * * @param attributes * A map of all attribute identifiers to their corresponding values. diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/ConnectionGroup.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/ConnectionGroup.java index 8e34e416a..04b494a90 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/ConnectionGroup.java +++ b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/ConnectionGroup.java @@ -137,8 +137,17 @@ public interface ConnectionGroup extends Identifiable, Connectable { /** * Sets the given attributes. If an attribute within the map is not - * supported, it will simply be dropped. Any attributes not within the - * given map will be left untouched. + * supported, it will simply be dropped. Any attributes not within the given + * map will be left untouched. Attributes which are not declared within + * getConnectionGroupAttributes() of the associated UserContext MUST NOT be + * submitted, but other extensions may manipulate the declared attributes + * through decorate() and redecorate(). + * + * Implementations may optionally allow storage of unsupported attributes. + * Extensions which rely on other extensions to store their attribute + * values should verify that such storage is supported by first testing + * that the attribute value is retrievable via getAttributes() after being + * set. * * @param attributes * A map of all attribute identifiers to their corresponding values. diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/SharingProfile.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/SharingProfile.java index f9ec34c84..3b4ec6570 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/SharingProfile.java +++ b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/SharingProfile.java @@ -107,7 +107,16 @@ public interface SharingProfile extends Identifiable { /** * Sets the given attributes. If an attribute within the map is not * supported, it will simply be dropped. Any attributes not within the - * given map will be left untouched. + * given map will be left untouched. Attributes which are not declared + * within getSharingProfileAttributes() of the associated UserContext MUST + * NOT be submitted, but other extensions may manipulate the declared + * attributes through decorate() and redecorate(). + * + * Implementations may optionally allow storage of unsupported attributes. + * Extensions which rely on other extensions to store their attribute + * values should verify that such storage is supported by first testing + * that the attribute value is retrievable via getAttributes() after being + * set. * * @param attributes * A map of all attribute identifiers to their corresponding values. diff --git a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/User.java b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/User.java index f7bd61ca2..49e1f9923 100644 --- a/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/User.java +++ b/guacamole-ext/src/main/java/org/apache/guacamole/net/auth/User.java @@ -94,8 +94,17 @@ public interface User extends Identifiable { /** * Sets the given attributes. If an attribute within the map is not - * supported, it will simply be dropped. Any attributes not within the - * given map will be left untouched. + * supported, it will simply be dropped. Any attributes not within the given + * map will be left untouched. Attributes which are not declared within + * getUserAttributes() of the associated UserContext MUST NOT be submitted, + * but other extensions may manipulate the declared attributes through + * decorate() and redecorate(). + * + * Implementations may optionally allow storage of unsupported attributes. + * Extensions which rely on other extensions to store their attribute + * values should verify that such storage is supported by first testing + * that the attribute value is retrievable via getAttributes() after being + * set. * * @param attributes * A map of all attribute identifiers to their corresponding values.