From 3c00b77d981e799733a16b95a7b3510984a494af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=CC=88rg=20Prante?= Date: Thu, 17 Jan 2019 15:42:07 +0100 Subject: [PATCH] beginning work of adding limitation and validation framework to http parameters, playing with old oauth code --- build.gradle | 52 ++- gradle.properties | 4 +- gradle/qa.gradle | 37 --- gradle/wrapper/gradle-wrapper.jar | Bin 54413 -> 55190 bytes gradle/wrapper/gradle-wrapper.properties | 4 +- gradlew | 2 +- gradlew.bat | 2 +- net-http/build.gradle | 3 + .../org/xbib/net/http/HttpParameters.java | 298 +++++++++++++++++ .../java/org/xbib/net/http/HttpRequest.java | 30 ++ .../java/org/xbib/net/http/HttpResponse.java | 15 + .../net/http/UrlStringRequestAdapter.java | 49 +++ .../net/http/util/LimitedSortedStringSet.java | 28 ++ .../xbib/net/http/util/LimitedStringMap.java | 25 ++ net-oauth/build.gradle | 3 + .../xbib/net/oauth/AbstractOAuthConsumer.java | 237 ++++++++++++++ .../xbib/net/oauth/AbstractOAuthProvider.java | 299 ++++++++++++++++++ .../xbib/net/oauth/DefaultOAuthConsumer.java | 26 ++ .../xbib/net/oauth/DefaultOAuthProvider.java | 42 +++ .../HttpURLConnectionRequestAdapter.java | 61 ++++ .../HttpURLConnectionResponseAdapter.java | 36 +++ .../main/java/org/xbib/net/oauth/OAuth.java | 285 +++++++++++++++++ .../oauth/OAuthCommunicationException.java | 21 ++ .../org/xbib/net/oauth/OAuthConsumer.java | 157 +++++++++ .../org/xbib/net/oauth/OAuthException.java | 17 + .../OAuthExpectationFailedException.java | 9 + .../oauth/OAuthMessageSignerException.java | 14 + .../oauth/OAuthNotAuthorizedException.java | 24 ++ .../org/xbib/net/oauth/OAuthProvider.java | 206 ++++++++++++ .../xbib/net/oauth/OAuthProviderListener.java | 47 +++ .../AuthorizationHeaderSigningStrategy.java | 42 +++ .../net/oauth/sign/HmacSha1MessageSigner.java | 45 +++ .../oauth/sign/HmacSha256MessageSigner.java | 45 +++ .../net/oauth/sign/OAuthMessageSigner.java | 54 ++++ .../oauth/sign/PlainTextMessageSigner.java | 29 ++ .../sign/QueryStringSigningStrategy.java | 41 +++ .../net/oauth/sign/SignatureBaseString.java | 96 ++++++ .../xbib/net/oauth/sign/SigningStrategy.java | 37 +++ .../java/org/xbib/net/QueryParameters.java | 2 +- net-url/src/main/java/org/xbib/net/URL.java | 6 + settings.gradle | 1 + 41 files changed, 2385 insertions(+), 46 deletions(-) delete mode 100644 gradle/qa.gradle create mode 100644 net-http/build.gradle create mode 100644 net-http/src/main/java/org/xbib/net/http/HttpParameters.java create mode 100644 net-http/src/main/java/org/xbib/net/http/HttpRequest.java create mode 100644 net-http/src/main/java/org/xbib/net/http/HttpResponse.java create mode 100644 net-http/src/main/java/org/xbib/net/http/UrlStringRequestAdapter.java create mode 100644 net-http/src/main/java/org/xbib/net/http/util/LimitedSortedStringSet.java create mode 100644 net-http/src/main/java/org/xbib/net/http/util/LimitedStringMap.java create mode 100644 net-oauth/build.gradle create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/AbstractOAuthConsumer.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/AbstractOAuthProvider.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/DefaultOAuthConsumer.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/DefaultOAuthProvider.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/HttpURLConnectionRequestAdapter.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/HttpURLConnectionResponseAdapter.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuth.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuthCommunicationException.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuthConsumer.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuthException.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuthExpectationFailedException.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuthMessageSignerException.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuthNotAuthorizedException.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuthProvider.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/OAuthProviderListener.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/sign/AuthorizationHeaderSigningStrategy.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/sign/HmacSha1MessageSigner.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/sign/HmacSha256MessageSigner.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/sign/OAuthMessageSigner.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/sign/PlainTextMessageSigner.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/sign/QueryStringSigningStrategy.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/sign/SignatureBaseString.java create mode 100644 net-oauth/src/main/java/org/xbib/net/oauth/sign/SigningStrategy.java diff --git a/build.gradle b/build.gradle index 440fb9a..3d514a0 100644 --- a/build.gradle +++ b/build.gradle @@ -2,6 +2,7 @@ plugins { id "org.sonarqube" version "2.6.1" id "io.codearte.nexus-staging" version "0.11.0" + id "com.github.spotbugs" version "1.6.9" id "org.xbib.gradle.plugin.asciidoctor" version "1.5.6.0.1" } @@ -25,7 +26,7 @@ subprojects { apply plugin: 'maven' apply plugin: 'signing' apply plugin: 'checkstyle' - apply plugin: 'findbugs' + apply plugin: 'com.github.spotbugs' apply plugin: 'pmd' apply plugin: 'org.xbib.gradle.plugin.asciidoctor' @@ -91,7 +92,7 @@ subprojects { javadoc { options.docletpath = configurations.asciidoclet.files.asType(List) options.doclet = 'org.asciidoctor.Asciidoclet' - options.overview = "src/docs/asciidoclet/overview.adoc" + //options.overview = "src/docs/asciidoclet/overview.adoc" options.addStringOption "-base-dir", "${projectDir}" options.addStringOption "-attribute", "name=${project.name},version=${project.version},title-link=https://github.com/xbib/${project.name}" @@ -120,7 +121,52 @@ subprojects { } apply from: "${rootProject.projectDir}/gradle/publish.gradle" - apply from: "${rootProject.projectDir}/gradle/qa.gradle" + + tasks.withType(Checkstyle) { + ignoreFailures = true + reports { + xml.enabled = true + html.enabled = true + } + } + + tasks.withType(Pmd) { + ignoreFailures = true + reports { + xml.enabled = true + html.enabled = true + } + } + + checkstyle { + configFile = rootProject.file('config/checkstyle/checkstyle.xml') + ignoreFailures = true + showViolations = true + } + + sonarqube { + properties { + property "sonar.projectName", "${project.group} ${project.name}" + property "sonar.sourceEncoding", "UTF-8" + property "sonar.tests", "src/test/java" + property "sonar.scm.provider", "git" + property "sonar.junit.reportsPath", "build/test-results/test/" + } + } + + spotbugs { + effort = "max" + reportLevel = "low" + //includeFilter = file("findbugs-exclude.xml") + } + + tasks.withType(com.github.spotbugs.SpotBugsTask) { + ignoreFailures = true + reports { + xml.enabled = false + html.enabled = true + } + } } nexusStaging { diff --git a/gradle.properties b/gradle.properties index aaf1cec..7fc1ee4 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,8 +1,10 @@ group = org.xbib name = net -version = 1.1.3 +version = 1.2.0 jackson.version = 2.8.11 junit.version = 4.12 wagon.version = 3.0.0 asciidoclet.version = 1.5.4 + +org.gradle.warning.mode=all diff --git a/gradle/qa.gradle b/gradle/qa.gradle deleted file mode 100644 index 98fed8d..0000000 --- a/gradle/qa.gradle +++ /dev/null @@ -1,37 +0,0 @@ -tasks.withType(Checkstyle) { - ignoreFailures = true - reports { - xml.enabled = true - html.enabled = true - } -} -tasks.withType(FindBugs) { - ignoreFailures = true - reports { - xml.enabled = false - html.enabled = true - } -} -tasks.withType(Pmd) { - ignoreFailures = true - reports { - xml.enabled = true - html.enabled = true - } -} - -checkstyle { - configFile = rootProject.file('config/checkstyle/checkstyle.xml') - ignoreFailures = true - showViolations = true -} - -sonarqube { - properties { - property "sonar.projectName", "${project.group} ${project.name}" - property "sonar.sourceEncoding", "UTF-8" - property "sonar.tests", "src/test/java" - property "sonar.scm.provider", "git" - property "sonar.junit.reportsPath", "build/test-results/test/" - } -} diff --git a/gradle/wrapper/gradle-wrapper.jar b/gradle/wrapper/gradle-wrapper.jar index 0d4a9516871afd710a9d84d89e31ba77745607bd..87b738cbd051603d91cc39de6cb000dd98fe6b02 100644 GIT binary patch literal 55190 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 z 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 diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index 91dafca..f0f2faa 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/gradle/wrapper/gradle-wrapper.properties @@ -1,6 +1,6 @@ -#Fri Sep 14 16:19:33 CEST 2018 +#Thu Jan 17 15:23:55 CET 2019 distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists -distributionUrl=https\://services.gradle.org/distributions/gradle-4.9-all.zip +distributionUrl=https\://services.gradle.org/distributions/gradle-5.1-all.zip diff --git a/gradlew b/gradlew index cccdd3d..af6708f 100755 --- a/gradlew +++ b/gradlew @@ -28,7 +28,7 @@ APP_NAME="Gradle" APP_BASE_NAME=`basename "$0"` # Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. -DEFAULT_JVM_OPTS="" +DEFAULT_JVM_OPTS='"-Xmx64m"' # Use the maximum available, or set MAX_FD != -1 to use that value. MAX_FD="maximum" diff --git a/gradlew.bat b/gradlew.bat index e95643d..0f8d593 100644 --- a/gradlew.bat +++ b/gradlew.bat @@ -14,7 +14,7 @@ set APP_BASE_NAME=%~n0 set APP_HOME=%DIRNAME% @rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script. -set DEFAULT_JVM_OPTS= +set DEFAULT_JVM_OPTS="-Xmx64m" @rem Find java.exe if defined JAVA_HOME goto findJavaFromJavaHome diff --git a/net-http/build.gradle b/net-http/build.gradle new file mode 100644 index 0000000..21aeee4 --- /dev/null +++ b/net-http/build.gradle @@ -0,0 +1,3 @@ +dependencies { + compile project(':net-url') +} diff --git a/net-http/src/main/java/org/xbib/net/http/HttpParameters.java b/net-http/src/main/java/org/xbib/net/http/HttpParameters.java new file mode 100644 index 0000000..bd94a75 --- /dev/null +++ b/net-http/src/main/java/org/xbib/net/http/HttpParameters.java @@ -0,0 +1,298 @@ +package org.xbib.net.http; + +import org.xbib.net.PercentDecoder; +import org.xbib.net.PercentEncoder; +import org.xbib.net.PercentEncoders; +import org.xbib.net.http.util.LimitedSortedStringSet; +import org.xbib.net.http.util.LimitedStringMap; + +import java.nio.charset.MalformedInputException; +import java.nio.charset.StandardCharsets; +import java.nio.charset.UnmappableCharacterException; +import java.util.Collection; +import java.util.Iterator; +import java.util.List; +import java.util.Map; +import java.util.Set; +import java.util.SortedSet; + +/** + * A limited multi-map of HTTP request parameters. Each key references a + * limited set of parameters collected from the request during message + * signing. Parameter values are sorted as per + * OAuth specification. + * Every key/value pair will be percent-encoded upon insertion. + * This class has special semantics tailored to + * being useful for message signing; it's not a general purpose collection class + * to handle request parameters. + */ +public class HttpParameters implements Map> { + + private final LimitedStringMap wrappedMap; + + private final PercentEncoder percentEncoder; + + private final PercentDecoder percentDecoder; + + public HttpParameters() { + this.wrappedMap = new LimitedStringMap(); + this.percentEncoder = PercentEncoders.getQueryEncoder(StandardCharsets.UTF_8); + this.percentDecoder = new PercentDecoder(); + } + + @Override + public SortedSet put(String key, SortedSet value) { + return wrappedMap.put(key, value); + } + + @Override + public SortedSet get(Object key) { + return wrappedMap.get(key); + } + + @Override + public void putAll(Map> m) { + wrappedMap.putAll(m); + } + + @Override + public boolean containsKey(Object key) { + return wrappedMap.containsKey(key); + } + + @Override + public boolean containsValue(Object value) { + if (value instanceof String) { + for (Set values : wrappedMap.values()) { + if (values.contains(value)) { + return true; + } + } + } + return false; + } + + @Override + public int size() { + int count = 0; + for (String key : wrappedMap.keySet()) { + count += wrappedMap.get(key).size(); + } + return count; + } + + @Override + public boolean isEmpty() { + return wrappedMap.isEmpty(); + } + + @Override + public void clear() { + wrappedMap.clear(); + } + + @Override + public SortedSet remove(Object key) { + return wrappedMap.remove(key); + } + + @Override + public Set keySet() { + return wrappedMap.keySet(); + } + + @Override + public Collection> values() { + return wrappedMap.values(); + } + + @Override + public Set>> entrySet() { + return wrappedMap.entrySet(); + } + + public SortedSet put(String key, SortedSet values, boolean percentEncode) + throws MalformedInputException, UnmappableCharacterException { + if (percentEncode) { + remove(key); + for (String v : values) { + put(key, v, true); + } + return get(key); + } else { + return wrappedMap.put(key, values); + } + } + + /** + * Convenience method to add a single value for the parameter specified by 'key'. + * + * @param key the parameter name + * @param value the parameter value + * @return the value + */ + public String put(String key, String value) + throws MalformedInputException, UnmappableCharacterException { + return put(key, value, false); + } + + /** + * Convenience method to add a single value for the parameter specified by + * 'key'. + * + * @param key the parameter name + * @param value the parameter value + * @param percentEncode whether key and value should be percent encoded before being + * inserted into the map + * @return the value + */ + public String put(String key, String value, boolean percentEncode) + throws MalformedInputException, UnmappableCharacterException { + String k = percentEncode ? percentEncoder.encode(key) : key; + SortedSet values = wrappedMap.get(k); + if (values == null) { + values = new LimitedSortedStringSet(); + wrappedMap.put(k, values); + } + String v = null; + if (value != null) { + v = percentEncode ? percentEncoder.encode(value) : value; + values.add(v); + } + return v; + } + + /** + * Convenience method to allow for storing null values. {@link #put} doesn't + * allow null values, because that would be ambiguous. + * + * @param key the parameter name + * @param nullString can be anything, but probably... null? + * @return null + */ + public String putNull(String key, String nullString) + throws MalformedInputException, UnmappableCharacterException { + return put(key, nullString); + } + + public void putAll(Map> m, boolean percentEncode) + throws MalformedInputException, UnmappableCharacterException { + if (percentEncode) { + for (String key : m.keySet()) { + put(key, m.get(key), true); + } + } else { + wrappedMap.putAll(m); + } + } + + public void putAll(String[] keyValuePairs, boolean percentEncode) + throws MalformedInputException, UnmappableCharacterException { + for (int i = 0; i < keyValuePairs.length - 1; i += 2) { + this.put(keyValuePairs[i], keyValuePairs[i + 1], percentEncode); + } + } + + /** + * Convenience method to merge a Map>. + * + * @param m the map + */ + public void putMap(Map> m) { + for (String key : m.keySet()) { + SortedSet vals = get(key); + if (vals == null) { + vals = new LimitedSortedStringSet(); + put(key, vals); + } + vals.addAll(m.get(key)); + } + } + + + public String getFirst(String key) + throws MalformedInputException, UnmappableCharacterException { + return getFirst(key, false); + } + + /** + * Returns the first value from the set of all values for the given + * parameter name. If the key passed to this method contains special + * characters, you must first percent encode it, otherwise the lookup will fail + * (that's because upon storing values in this map, keys get + * percent-encoded). + * + * @param key the parameter name (must be percent encoded if it contains unsafe + * characters!) + * @param percentDecode whether the value being retrieved should be percent decoded + * @return the first value found for this parameter + */ + public String getFirst(String key, boolean percentDecode) + throws MalformedInputException, UnmappableCharacterException { + SortedSet values = wrappedMap.get(key); + if (values == null || values.isEmpty()) { + return null; + } + String value = values.first(); + return percentDecode ? percentDecoder.decode(value) : value; + } + + /** + * Concatenates all values for the given key to a list of key/value pairs + * suitable for use in a URL query string. + * + * @param key the parameter name + * @return the query string + */ + public String getAsQueryString(String key) + throws MalformedInputException, UnmappableCharacterException { + return getAsQueryString(key, true); + } + + /** + * Concatenates all values for the given key to a list of key/value pairs + * suitable for use in a URL query string. + * + * @param key the parameter name + * @param percentEncode whether key should be percent encoded before being + * used with the map + * @return the query string + */ + public String getAsQueryString(String key, boolean percentEncode) + throws MalformedInputException, UnmappableCharacterException { + String k = percentEncode ? percentEncoder.encode(key) : key; + SortedSet values = wrappedMap.get(k); + if (values == null) { + return k + "="; + } + Iterator it = values.iterator(); + StringBuilder sb = new StringBuilder(); + while (it.hasNext()) { + sb.append(k).append("=").append(it.next()); + if (it.hasNext()) { + sb.append("&"); + } + } + return sb.toString(); + } + + public String getAsHeaderElement(String key) + throws MalformedInputException, UnmappableCharacterException { + String value = getFirst(key); + if (value == null) { + return null; + } + return key + "=\"" + value + "\""; + } + + public HttpParameters getOAuthParameters() { + HttpParameters oauthParams = new HttpParameters(); + for (Entry> param : this.entrySet()) { + String key = param.getKey(); + if (key.startsWith("oauth_") || key.startsWith("x_oauth_")) { + oauthParams.put(key, param.getValue()); + } + } + return oauthParams; + } +} diff --git a/net-http/src/main/java/org/xbib/net/http/HttpRequest.java b/net-http/src/main/java/org/xbib/net/http/HttpRequest.java new file mode 100644 index 0000000..6ffb9a8 --- /dev/null +++ b/net-http/src/main/java/org/xbib/net/http/HttpRequest.java @@ -0,0 +1,30 @@ +package org.xbib.net.http; + +import java.io.IOException; +import java.io.InputStream; +import java.util.Map; + +/** + * A representation of an HTTP request. Contains methods to access all + * those parts of an HTTP request. + */ +public interface HttpRequest { + + String getMethod(); + + String getRequestUrl(); + + void setRequestUrl(String url); + + void setHeader(String name, String value); + + String getHeader(String name); + + Map getAllHeaders(); + + InputStream getMessagePayload() throws IOException; + + String getContentType(); + + Object unwrap(); +} diff --git a/net-http/src/main/java/org/xbib/net/http/HttpResponse.java b/net-http/src/main/java/org/xbib/net/http/HttpResponse.java new file mode 100644 index 0000000..6dfd13b --- /dev/null +++ b/net-http/src/main/java/org/xbib/net/http/HttpResponse.java @@ -0,0 +1,15 @@ +package org.xbib.net.http; + +import java.io.IOException; +import java.io.InputStream; + +public interface HttpResponse { + + int getStatusCode() throws IOException; + + String getReasonPhrase() throws Exception; + + InputStream getContent() throws IOException; + + Object unwrap(); +} diff --git a/net-http/src/main/java/org/xbib/net/http/UrlStringRequestAdapter.java b/net-http/src/main/java/org/xbib/net/http/UrlStringRequestAdapter.java new file mode 100644 index 0000000..51a68f7 --- /dev/null +++ b/net-http/src/main/java/org/xbib/net/http/UrlStringRequestAdapter.java @@ -0,0 +1,49 @@ +package org.xbib.net.http; + +import java.io.InputStream; +import java.util.Collections; +import java.util.Map; + +public class UrlStringRequestAdapter implements HttpRequest { + + private String url; + + public UrlStringRequestAdapter(String url) { + this.url = url; + } + + public String getMethod() { + return "GET"; + } + + public String getRequestUrl() { + return url; + } + + public void setRequestUrl(String url) { + this.url = url; + } + + public void setHeader(String name, String value) { + } + + public String getHeader(String name) { + return null; + } + + public Map getAllHeaders() { + return Collections.emptyMap(); + } + + public InputStream getMessagePayload() { + return null; + } + + public String getContentType() { + return null; + } + + public Object unwrap() { + return url; + } +} diff --git a/net-http/src/main/java/org/xbib/net/http/util/LimitedSortedStringSet.java b/net-http/src/main/java/org/xbib/net/http/util/LimitedSortedStringSet.java new file mode 100644 index 0000000..a2ed914 --- /dev/null +++ b/net-http/src/main/java/org/xbib/net/http/util/LimitedSortedStringSet.java @@ -0,0 +1,28 @@ +package org.xbib.net.http.util; + +import java.util.SortedSet; +import java.util.TreeSet; + +public class LimitedSortedStringSet extends TreeSet implements SortedSet { + + private final int sizeLimit; + + private final int elementSizeLimit; + + public LimitedSortedStringSet() { + this(1024, 65536); + } + + public LimitedSortedStringSet(int sizeLimit, int elementSizeLimit) { + this.sizeLimit = sizeLimit; + this.elementSizeLimit = elementSizeLimit; + } + + @Override + public boolean add(String string) { + if (size() < sizeLimit && string.length() <= elementSizeLimit ) { + return super.add(string); + } + return false; + } +} diff --git a/net-http/src/main/java/org/xbib/net/http/util/LimitedStringMap.java b/net-http/src/main/java/org/xbib/net/http/util/LimitedStringMap.java new file mode 100644 index 0000000..c947437 --- /dev/null +++ b/net-http/src/main/java/org/xbib/net/http/util/LimitedStringMap.java @@ -0,0 +1,25 @@ +package org.xbib.net.http.util; + +import java.util.SortedSet; +import java.util.TreeMap; + +public class LimitedStringMap extends TreeMap> { + + private final int limit; + + public LimitedStringMap() { + this(1024); + } + + public LimitedStringMap(int limit) { + this.limit = limit; + } + + @Override + public SortedSet put(String key, SortedSet value) { + if (size() < limit) { + return super.put(key, value); + } + return null; + } +} diff --git a/net-oauth/build.gradle b/net-oauth/build.gradle new file mode 100644 index 0000000..0cb40e7 --- /dev/null +++ b/net-oauth/build.gradle @@ -0,0 +1,3 @@ +dependencies { + compile project(':net-http') +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/AbstractOAuthConsumer.java b/net-oauth/src/main/java/org/xbib/net/oauth/AbstractOAuthConsumer.java new file mode 100644 index 0000000..fb90280 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/AbstractOAuthConsumer.java @@ -0,0 +1,237 @@ +package org.xbib.net.oauth; + +import java.io.IOException; +import java.io.InputStream; +import java.nio.charset.MalformedInputException; +import java.nio.charset.UnmappableCharacterException; +import java.security.SecureRandom; +import java.util.Random; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.http.UrlStringRequestAdapter; +import org.xbib.net.oauth.sign.AuthorizationHeaderSigningStrategy; +import org.xbib.net.oauth.sign.HmacSha1MessageSigner; +import org.xbib.net.oauth.sign.OAuthMessageSigner; +import org.xbib.net.oauth.sign.QueryStringSigningStrategy; +import org.xbib.net.oauth.sign.SigningStrategy; + +/** + * ABC for consumer implementations. If you're developing a custom consumer you + * will probably inherit from this class to save you a lot of work. + * + */ +public abstract class AbstractOAuthConsumer implements OAuthConsumer { + + private String consumerKey, consumerSecret; + + private String token; + + private OAuthMessageSigner messageSigner; + + private SigningStrategy signingStrategy; + + // these are params that may be passed to the consumer directly (i.e. + // without going through the request object) + private HttpParameters additionalParameters; + + // these are the params which will be passed to the message signer + private HttpParameters requestParameters; + + private boolean sendEmptyTokens; + + private final Random random = new SecureRandom(); + + public AbstractOAuthConsumer(String consumerKey, String consumerSecret) { + this.consumerKey = consumerKey; + this.consumerSecret = consumerSecret; + setMessageSigner(new HmacSha1MessageSigner()); + setSigningStrategy(new AuthorizationHeaderSigningStrategy()); + } + + public void setMessageSigner(OAuthMessageSigner messageSigner) { + this.messageSigner = messageSigner; + messageSigner.setConsumerSecret(consumerSecret); + } + + public void setSigningStrategy(SigningStrategy signingStrategy) { + this.signingStrategy = signingStrategy; + } + + public void setAdditionalParameters(HttpParameters additionalParameters) { + this.additionalParameters = additionalParameters; + } + + public synchronized HttpRequest sign(HttpRequest request) throws OAuthMessageSignerException, + OAuthExpectationFailedException, OAuthCommunicationException { + if (consumerKey == null) { + throw new OAuthExpectationFailedException("consumer key not set"); + } + if (consumerSecret == null) { + throw new OAuthExpectationFailedException("consumer secret not set"); + } + requestParameters = new HttpParameters(); + try { + if (additionalParameters != null) { + requestParameters.putAll(additionalParameters, false); + } + collectHeaderParameters(request, requestParameters); + collectQueryParameters(request, requestParameters); + collectBodyParameters(request, requestParameters); + // add any OAuth params that haven't already been set + completeOAuthParameters(requestParameters); + requestParameters.remove(OAuth.OAUTH_SIGNATURE); + } catch (IOException e) { + throw new OAuthCommunicationException(e); + } + String signature = messageSigner.sign(request, requestParameters); + try { + signingStrategy.writeSignature(signature, request, requestParameters); + } catch (MalformedInputException | UnmappableCharacterException e) { + throw new OAuthMessageSignerException(e); + } + return request; + } + + public synchronized HttpRequest sign(Object request) throws OAuthMessageSignerException, + OAuthExpectationFailedException, OAuthCommunicationException { + return sign(wrap(request)); + } + + public synchronized String sign(String url) throws OAuthMessageSignerException, + OAuthExpectationFailedException, OAuthCommunicationException { + HttpRequest request = new UrlStringRequestAdapter(url); + // switch to URL signing + SigningStrategy oldStrategy = this.signingStrategy; + this.signingStrategy = new QueryStringSigningStrategy(); + sign(request); + // revert to old strategy + this.signingStrategy = oldStrategy; + return request.getRequestUrl(); + } + + /** + * Adapts the given request object to a Signpost {@link HttpRequest}. How + * this is done depends on the consumer implementation. + * + * @param request + * the native HTTP request instance + * @return the adapted request + */ + protected abstract HttpRequest wrap(Object request); + + public void setTokenWithSecret(String token, String tokenSecret) { + this.token = token; + messageSigner.setTokenSecret(tokenSecret); + } + + public String getToken() { + return token; + } + + public String getTokenSecret() { + return messageSigner.getTokenSecret(); + } + + public String getConsumerKey() { + return this.consumerKey; + } + + public String getConsumerSecret() { + return this.consumerSecret; + } + + /** + *

+ * Helper method that adds any OAuth parameters to the given request + * parameters which are missing from the current request but required for + * signing. A good example is the oauth_nonce parameter, which is typically + * not provided by the client in advance. + *

+ *

+ * It's probably not a very good idea to override this method. If you want + * to generate different nonces or timestamps, override + * {@link #generateNonce()} or {@link #generateTimestamp()} instead. + *

+ * + * @param out + * the request parameter which should be completed + */ + protected void completeOAuthParameters(HttpParameters out) + throws MalformedInputException, UnmappableCharacterException { + if (!out.containsKey(OAuth.OAUTH_CONSUMER_KEY)) { + out.put(OAuth.OAUTH_CONSUMER_KEY, consumerKey, true); + } + if (!out.containsKey(OAuth.OAUTH_SIGNATURE_METHOD)) { + out.put(OAuth.OAUTH_SIGNATURE_METHOD, messageSigner.getSignatureMethod(), true); + } + if (!out.containsKey(OAuth.OAUTH_TIMESTAMP)) { + out.put(OAuth.OAUTH_TIMESTAMP, generateTimestamp(), true); + } + if (!out.containsKey(OAuth.OAUTH_NONCE)) { + out.put(OAuth.OAUTH_NONCE, generateNonce(), true); + } + if (!out.containsKey(OAuth.OAUTH_VERSION)) { + out.put(OAuth.OAUTH_VERSION, OAuth.VERSION_1_0, true); + } + if (!out.containsKey(OAuth.OAUTH_TOKEN)) { + if (token != null && !token.equals("") || sendEmptyTokens) { + out.put(OAuth.OAUTH_TOKEN, token, true); + } + } + } + + public HttpParameters getRequestParameters() { + return requestParameters; + } + + public void setSendEmptyTokens(boolean enable) { + this.sendEmptyTokens = enable; + } + + /** + * Collects OAuth Authorization header parameters as per OAuth Core 1.0 spec + * section 9.1.1 + */ + protected void collectHeaderParameters(HttpRequest request, HttpParameters out) + throws MalformedInputException, UnmappableCharacterException { + HttpParameters headerParams = OAuth.oauthHeaderToParamsMap(request.getHeader(OAuth.HTTP_AUTHORIZATION_HEADER)); + out.putAll(headerParams, false); + } + + /** + * Collects x-www-form-urlencoded body parameters as per OAuth Core 1.0 spec + * section 9.1.1 + */ + protected void collectBodyParameters(HttpRequest request, HttpParameters out) + throws IOException { + // collect x-www-form-urlencoded body params + String contentType = request.getContentType(); + if (contentType != null && contentType.startsWith(OAuth.FORM_ENCODED)) { + InputStream payload = request.getMessagePayload(); + out.putAll(OAuth.decodeForm(payload), true); + } + } + + /** + * Collects HTTP GET query string parameters as per OAuth Core 1.0 spec + * section 9.1.1 + */ + protected void collectQueryParameters(HttpRequest request, HttpParameters out) + throws MalformedInputException, UnmappableCharacterException { + String url = request.getRequestUrl(); + int q = url.indexOf('?'); + if (q >= 0) { + // Combine the URL query string with the other parameters: + out.putAll(OAuth.decodeForm(url.substring(q + 1)), true); + } + } + + protected String generateTimestamp() { + return Long.toString(System.currentTimeMillis() / 1000L); + } + + protected String generateNonce() { + return Long.toString(random.nextLong()); + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/AbstractOAuthProvider.java b/net-oauth/src/main/java/org/xbib/net/oauth/AbstractOAuthProvider.java new file mode 100644 index 0000000..29d309e --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/AbstractOAuthProvider.java @@ -0,0 +1,299 @@ +package org.xbib.net.oauth; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.http.HttpResponse; + +import java.io.BufferedReader; +import java.io.InputStreamReader; +import java.nio.charset.MalformedInputException; +import java.nio.charset.UnmappableCharacterException; +import java.util.HashMap; +import java.util.Map; + +/** + * For all provider implementations. If you're writing a custom provider, + * you will probably inherit from this class, since it takes a lot of work from + * you. + */ +public abstract class AbstractOAuthProvider implements OAuthProvider { + + private final String requestTokenEndpointUrl; + + private final String accessTokenEndpointUrl; + + private final String authorizationWebsiteUrl; + + private HttpParameters responseParameters; + + private Map defaultHeaders; + + private boolean isOAuth10a; + + private OAuthProviderListener listener; + + public AbstractOAuthProvider(String requestTokenEndpointUrl, String accessTokenEndpointUrl, + String authorizationWebsiteUrl) { + this.requestTokenEndpointUrl = requestTokenEndpointUrl; + this.accessTokenEndpointUrl = accessTokenEndpointUrl; + this.authorizationWebsiteUrl = authorizationWebsiteUrl; + this.responseParameters = new HttpParameters(); + this.defaultHeaders = new HashMap(); + } + + public synchronized String retrieveRequestToken(OAuthConsumer consumer, String callbackUrl, + String... customOAuthParams) throws OAuthMessageSignerException, + OAuthNotAuthorizedException, OAuthExpectationFailedException, + OAuthCommunicationException { + // invalidate current credentials, if any + consumer.setTokenWithSecret(null, null); + // 1.0a expects the callback to be sent while getting the request token. + // 1.0 service providers would simply ignore this parameter. + HttpParameters params = new HttpParameters(); + try { + params.putAll(customOAuthParams, true); + params.put(OAuth.OAUTH_CALLBACK, callbackUrl, true); + retrieveToken(consumer, requestTokenEndpointUrl, params); + String callbackConfirmed = responseParameters.getFirst(OAuth.OAUTH_CALLBACK_CONFIRMED); + responseParameters.remove(OAuth.OAUTH_CALLBACK_CONFIRMED); + isOAuth10a = Boolean.TRUE.toString().equals(callbackConfirmed); + // 1.0 service providers expect the callback as part of the auth URL, + // Do not send when 1.0a. + if (isOAuth10a) { + return OAuth.addQueryParameters(authorizationWebsiteUrl, OAuth.OAUTH_TOKEN, + consumer.getToken()); + } else { + return OAuth.addQueryParameters(authorizationWebsiteUrl, OAuth.OAUTH_TOKEN, + consumer.getToken(), OAuth.OAUTH_CALLBACK, callbackUrl); + } + } catch (MalformedInputException | UnmappableCharacterException e) { + throw new OAuthMessageSignerException(e); + } + } + + public synchronized void retrieveAccessToken(OAuthConsumer consumer, String oauthVerifier, + String... customOAuthParams) throws OAuthMessageSignerException, + OAuthNotAuthorizedException, OAuthExpectationFailedException, + OAuthCommunicationException { + if (consumer.getToken() == null || consumer.getTokenSecret() == null) { + throw new OAuthExpectationFailedException( + "Authorized request token or token secret not set. " + + "Did you retrieve an authorized request token before?"); + } + HttpParameters params = new HttpParameters(); + try { + params.putAll(customOAuthParams, true); + if (isOAuth10a && oauthVerifier != null) { + params.put(OAuth.OAUTH_VERIFIER, oauthVerifier, true); + } + } catch (MalformedInputException | UnmappableCharacterException e) { + throw new OAuthMessageSignerException(e); + } + retrieveToken(consumer, accessTokenEndpointUrl, params); + } + + /** + * Implemented by subclasses. The responsibility of this method is to + * contact the service provider at the given endpoint URL and fetch a + * request or access token. What kind of token is retrieved solely depends + * on the URL being used. + * Correct implementations of this method must guarantee the following + * post-conditions: + *
    + *
  • the {@link OAuthConsumer} passed to this method must have a valid + * {@link OAuth#OAUTH_TOKEN} and {@link OAuth#OAUTH_TOKEN_SECRET} set by + * calling {@link OAuthConsumer#setTokenWithSecret(String, String)}
    • + *
  • {@link #getResponseParameters()} must return the set of query + * parameters served by the service provider in the token response, with all + * OAuth specific parameters being removed
    • + *
+ * + * @param consumer the {@link OAuthConsumer} that should be used to sign the request + * @param endpointUrl the URL at which the service provider serves the OAuth token that + * is to be fetched + * @param customOAuthParams you can pass custom OAuth parameters here (such as oauth_callback + * or oauth_verifier) which will go directly into the signer, i.e. + * you don't have to put them into the request first. + * @throws OAuthMessageSignerException if signing the token request fails + * @throws OAuthCommunicationException if a network communication error occurs + * @throws OAuthNotAuthorizedException if the server replies 401 - Unauthorized + * @throws OAuthExpectationFailedException if an expectation has failed, e.g. because the server didn't + * reply in the expected format + */ + protected void retrieveToken(OAuthConsumer consumer, String endpointUrl, + HttpParameters customOAuthParams) throws OAuthMessageSignerException, + OAuthCommunicationException, OAuthNotAuthorizedException, + OAuthExpectationFailedException { + Map defaultHeaders = getRequestHeaders(); + if (consumer.getConsumerKey() == null || consumer.getConsumerSecret() == null) { + throw new OAuthExpectationFailedException("Consumer key or secret not set"); + } + HttpRequest request = null; + HttpResponse response = null; + try { + request = createRequest(endpointUrl); + for (String header : defaultHeaders.keySet()) { + request.setHeader(header, defaultHeaders.get(header)); + } + if (customOAuthParams != null && !customOAuthParams.isEmpty()) { + consumer.setAdditionalParameters(customOAuthParams); + } + if (this.listener != null) { + this.listener.prepareRequest(request); + } + consumer.sign(request); + if (this.listener != null) { + this.listener.prepareSubmission(request); + } + response = sendRequest(request); + int statusCode = response.getStatusCode(); + boolean requestHandled = false; + if (this.listener != null) { + requestHandled = this.listener.onResponseReceived(request, response); + } + if (requestHandled) { + return; + } + if (statusCode >= 300) { + handleUnexpectedResponse(statusCode, response); + } + HttpParameters responseParams = OAuth.decodeForm(response.getContent()); + String token = responseParams.getFirst(OAuth.OAUTH_TOKEN); + String secret = responseParams.getFirst(OAuth.OAUTH_TOKEN_SECRET); + responseParams.remove(OAuth.OAUTH_TOKEN); + responseParams.remove(OAuth.OAUTH_TOKEN_SECRET); + setResponseParameters(responseParams); + if (token == null || secret == null) { + throw new OAuthExpectationFailedException( + "Request token or token secret not set in server reply. " + + "The service provider you use is probably buggy."); + } + consumer.setTokenWithSecret(token, secret); + } catch (OAuthNotAuthorizedException | OAuthExpectationFailedException e) { + throw e; + } catch (Exception e) { + throw new OAuthCommunicationException(e); + } finally { + try { + closeConnection(request, response); + } catch (Exception e) { + throw new OAuthCommunicationException(e); + } + } + } + + protected void handleUnexpectedResponse(int statusCode, HttpResponse response) throws Exception { + if (response == null) { + return; + } + BufferedReader reader = new BufferedReader(new InputStreamReader(response.getContent())); + StringBuilder responseBody = new StringBuilder(); + String line = reader.readLine(); + while (line != null) { + responseBody.append(line); + line = reader.readLine(); + } + if (statusCode == 401) { + throw new OAuthNotAuthorizedException(responseBody.toString()); + } + throw new OAuthCommunicationException("Service provider responded in error: " + + statusCode + " (" + response.getReasonPhrase() + ")", responseBody.toString()); + } + + /** + * Overrride this method if you want to customize the logic for building a + * request object for the given endpoint URL. + * + * @param endpointUrl + * the URL to which the request will go + * @return the request object + * @throws Exception + * if something breaks + */ + protected abstract HttpRequest createRequest(String endpointUrl) throws Exception; + + /** + * Override this method if you want to customize the logic for how the given + * request is sent to the server. + * + * @param request + * the request to send + * @return the response to the request + * @throws Exception + * if something breaks + */ + protected abstract HttpResponse sendRequest(HttpRequest request) throws Exception; + + /** + * Called when the connection is being finalized after receiving the + * response. Use this to do any cleanup / resource freeing. + * + * @param request + * the request that has been sent + * @param response + * the response that has been received + * @throws Exception + * if something breaks + */ + protected void closeConnection(HttpRequest request, HttpResponse response) throws Exception { + // NOP + } + + public HttpParameters getResponseParameters() { + return responseParameters; + } + + /** + * Returns a single query parameter as served by the service provider in a + * token reply. You must call {@link #setResponseParameters} with the set of + * parameters before using this method. + * + * @param key + * the parameter name + * @return the parameter value + */ + protected String getResponseParameter(String key) + throws MalformedInputException, UnmappableCharacterException { + return responseParameters.getFirst(key); + } + + public void setResponseParameters(HttpParameters parameters) { + this.responseParameters = parameters; + } + + public void setOAuth10a(boolean isOAuth10aProvider) { + this.isOAuth10a = isOAuth10aProvider; + } + + public boolean isOAuth10a() { + return isOAuth10a; + } + + public String getRequestTokenEndpointUrl() { + return this.requestTokenEndpointUrl; + } + + public String getAccessTokenEndpointUrl() { + return this.accessTokenEndpointUrl; + } + + public String getAuthorizationWebsiteUrl() { + return this.authorizationWebsiteUrl; + } + + public void setRequestHeader(String header, String value) { + defaultHeaders.put(header, value); + } + + public Map getRequestHeaders() { + return defaultHeaders; + } + + public void setListener(OAuthProviderListener listener) { + this.listener = listener; + } + + public void removeListener(OAuthProviderListener listener) { + this.listener = null; + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/DefaultOAuthConsumer.java b/net-oauth/src/main/java/org/xbib/net/oauth/DefaultOAuthConsumer.java new file mode 100644 index 0000000..896eac5 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/DefaultOAuthConsumer.java @@ -0,0 +1,26 @@ +package org.xbib.net.oauth; + +import org.xbib.net.http.HttpRequest; + +import java.net.HttpURLConnection; + +/** + * The default implementation for an OAuth consumer. Only supports signing + * {@link HttpURLConnection} type requests. + */ +public class DefaultOAuthConsumer extends AbstractOAuthConsumer { + + public DefaultOAuthConsumer(String consumerKey, String consumerSecret) { + super(consumerKey, consumerSecret); + } + + @Override + protected HttpRequest wrap(Object request) { + if (!(request instanceof HttpURLConnection)) { + throw new IllegalArgumentException( + "The default consumer expects requests of type java.net.HttpURLConnection"); + } + return new HttpURLConnectionRequestAdapter((HttpURLConnection) request); + } + +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/DefaultOAuthProvider.java b/net-oauth/src/main/java/org/xbib/net/oauth/DefaultOAuthProvider.java new file mode 100644 index 0000000..7b6960c --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/DefaultOAuthProvider.java @@ -0,0 +1,42 @@ +package org.xbib.net.oauth; + +import org.xbib.net.http.HttpRequest; +import org.xbib.net.http.HttpResponse; + +import java.io.IOException; +import java.net.HttpURLConnection; +import java.net.URL; + +/** + * This default implementation uses {@link HttpURLConnection} type GET + * requests to receive tokens from a service provider. + */ +public class DefaultOAuthProvider extends AbstractOAuthProvider { + + public DefaultOAuthProvider(String requestTokenEndpointUrl, String accessTokenEndpointUrl, + String authorizationWebsiteUrl) { + super(requestTokenEndpointUrl, accessTokenEndpointUrl, authorizationWebsiteUrl); + } + + protected HttpRequest createRequest(String endpointUrl) throws IOException { + HttpURLConnection connection = (HttpURLConnection) new URL(endpointUrl).openConnection(); + connection.setRequestMethod("POST"); + connection.setAllowUserInteraction(false); + connection.setRequestProperty("Content-Length", "0"); + return new HttpURLConnectionRequestAdapter(connection); + } + + protected HttpResponse sendRequest(HttpRequest request) throws IOException { + HttpURLConnection connection = (HttpURLConnection) request.unwrap(); + connection.connect(); + return new HttpURLConnectionResponseAdapter(connection); + } + + @Override + protected void closeConnection(HttpRequest request, HttpResponse response) { + HttpURLConnection connection = (HttpURLConnection) request.unwrap(); + if (connection != null) { + connection.disconnect(); + } + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/HttpURLConnectionRequestAdapter.java b/net-oauth/src/main/java/org/xbib/net/oauth/HttpURLConnectionRequestAdapter.java new file mode 100644 index 0000000..c2df3a6 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/HttpURLConnectionRequestAdapter.java @@ -0,0 +1,61 @@ +package org.xbib.net.oauth; + +import org.xbib.net.http.HttpRequest; + +import java.io.InputStream; +import java.net.HttpURLConnection; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +public class HttpURLConnectionRequestAdapter implements HttpRequest { + + protected HttpURLConnection connection; + + public HttpURLConnectionRequestAdapter(HttpURLConnection connection) { + this.connection = connection; + } + + public String getMethod() { + return connection.getRequestMethod(); + } + + public String getRequestUrl() { + return connection.getURL().toExternalForm(); + } + + public void setRequestUrl(String url) { + } + + public void setHeader(String name, String value) { + connection.setRequestProperty(name, value); + } + + public String getHeader(String name) { + return connection.getRequestProperty(name); + } + + public Map getAllHeaders() { + Map> origHeaders = connection.getRequestProperties(); + Map headers = new HashMap(origHeaders.size()); + for (String name : origHeaders.keySet()) { + List values = origHeaders.get(name); + if (!values.isEmpty()) { + headers.put(name, values.get(0)); + } + } + return headers; + } + + public InputStream getMessagePayload() { + return null; + } + + public String getContentType() { + return connection.getRequestProperty("Content-Type"); + } + + public HttpURLConnection unwrap() { + return connection; + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/HttpURLConnectionResponseAdapter.java b/net-oauth/src/main/java/org/xbib/net/oauth/HttpURLConnectionResponseAdapter.java new file mode 100644 index 0000000..6990419 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/HttpURLConnectionResponseAdapter.java @@ -0,0 +1,36 @@ +package org.xbib.net.oauth; + +import org.xbib.net.http.HttpResponse; + +import java.io.IOException; +import java.io.InputStream; +import java.net.HttpURLConnection; + +public class HttpURLConnectionResponseAdapter implements HttpResponse { + + private HttpURLConnection connection; + + public HttpURLConnectionResponseAdapter(HttpURLConnection connection) { + this.connection = connection; + } + + public InputStream getContent() { + try { + return connection.getInputStream(); + } catch (IOException e) { + return connection.getErrorStream(); + } + } + + public int getStatusCode() throws IOException { + return connection.getResponseCode(); + } + + public String getReasonPhrase() throws Exception { + return connection.getResponseMessage(); + } + + public Object unwrap() { + return connection; + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuth.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuth.java new file mode 100644 index 0000000..94f5db2 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuth.java @@ -0,0 +1,285 @@ +package org.xbib.net.oauth; + +import org.xbib.net.PercentDecoder; +import org.xbib.net.PercentEncoder; +import org.xbib.net.PercentEncoders; +import org.xbib.net.http.HttpParameters; + +import java.io.BufferedReader; +import java.io.ByteArrayOutputStream; +import java.io.IOException; +import java.io.InputStream; +import java.io.InputStreamReader; +import java.io.OutputStream; +import java.nio.charset.MalformedInputException; +import java.nio.charset.StandardCharsets; +import java.nio.charset.UnmappableCharacterException; +import java.util.Collection; +import java.util.HashMap; +import java.util.Map; + +public class OAuth { + + public static final String VERSION_1_0 = "1.0"; + + public static final String ENCODING = "UTF-8"; + + public static final String FORM_ENCODED = "application/x-www-form-urlencoded"; + + public static final String HTTP_AUTHORIZATION_HEADER = "Authorization"; + + public static final String OAUTH_CONSUMER_KEY = "oauth_consumer_key"; + + public static final String OAUTH_TOKEN = "oauth_token"; + + public static final String OAUTH_TOKEN_SECRET = "oauth_token_secret"; + + public static final String OAUTH_SIGNATURE_METHOD = "oauth_signature_method"; + + public static final String OAUTH_SIGNATURE = "oauth_signature"; + + public static final String OAUTH_TIMESTAMP = "oauth_timestamp"; + + public static final String OAUTH_NONCE = "oauth_nonce"; + + public static final String OAUTH_VERSION = "oauth_version"; + + public static final String OAUTH_CALLBACK = "oauth_callback"; + + public static final String OAUTH_CALLBACK_CONFIRMED = "oauth_callback_confirmed"; + + public static final String OAUTH_VERIFIER = "oauth_verifier"; + + /** + * Pass this value as the callback "url" upon retrieving a request token if + * your application cannot receive callbacks (e.g. because it's a desktop + * app). This will tell the service provider that verification happens + * out-of-band, which basically means that it will generate a PIN code (the + * OAuth verifier) and display that to your user. You must obtain this code + * from your user and pass it to + * {@link OAuthProvider#retrieveAccessToken(OAuthConsumer, String, String...)} in order + * to complete the token handshake. + */ + public static final String OUT_OF_BAND = "oob"; + + public static final PercentEncoder percentEncoder = PercentEncoders.getQueryEncoder(StandardCharsets.UTF_8); + + public static final PercentDecoder percentDecoder = new PercentDecoder(); + + /** + * Construct a x-www-form-urlencoded document containing the given sequence + * of name/value pairs. Use OAuth percent encoding (not exactly the encoding + * mandated by x-www-form-urlencoded). + */ + public static > void formEncode(Collection parameters, + OutputStream into) throws IOException { + if (parameters != null) { + boolean first = true; + for (Map.Entry entry : parameters) { + if (first) { + first = false; + } else { + into.write('&'); + } + into.write(percentEncoder.encode(safeToString(entry.getKey())).getBytes()); + into.write('='); + into.write(percentEncoder.encode(safeToString(entry.getValue())).getBytes()); + } + } + } + + /** + * Construct a x-www-form-urlencoded document containing the given sequence + * of name/value pairs. Use OAuth percent encoding (not exactly the encoding + * mandated by x-www-form-urlencoded). + */ + public static > String formEncode(Collection parameters) + throws IOException { + ByteArrayOutputStream b = new ByteArrayOutputStream(); + formEncode(parameters, b); + return new String(b.toByteArray()); + } + + /** + * Parse a form-urlencoded document. + */ + public static HttpParameters decodeForm(String form) + throws MalformedInputException, UnmappableCharacterException { + HttpParameters params = new HttpParameters(); + if (isEmpty(form)) { + return params; + } + for (String nvp : form.split("\\&")) { + int equals = nvp.indexOf('='); + String name; + String value; + if (equals < 0) { + name = percentDecoder.decode(nvp); + value = null; + } else { + name = percentDecoder.decode(nvp.substring(0, equals)); + value = percentDecoder.decode(nvp.substring(equals + 1)); + } + + params.put(name, value); + } + return params; + } + + public static HttpParameters decodeForm(InputStream content) + throws IOException { + BufferedReader reader = new BufferedReader(new InputStreamReader( + content)); + StringBuilder sb = new StringBuilder(); + String line = reader.readLine(); + while (line != null) { + sb.append(line); + line = reader.readLine(); + } + + return decodeForm(sb.toString()); + } + + /** + * Construct a Map containing a copy of the given parameters. If several + * parameters have the same name, the Map will contain the first value, + * only. + */ + public static > Map toMap(Collection from) { + HashMap map = new HashMap(); + if (from != null) { + for (Map.Entry entry : from) { + String key = entry.getKey(); + if (!map.containsKey(key)) { + map.put(key, entry.getValue()); + } + } + } + return map; + } + + public static final String safeToString(Object from) { + return (from == null) ? null : from.toString(); + } + + public static boolean isEmpty(String str) { + return (str == null) || (str.length() == 0); + } + + /** + * Appends a list of key/value pairs to the given URL, e.g.: + * + * 
+     * String url = OAuth.addQueryParameters("http://example.com?a=1", b, 2, c, 3);
+     *
+ * + * which yields: + * + * 
+     * http://example.com?a=1&b=2&c=3
+     *
+ * + * All parameters will be encoded according to OAuth's percent encoding + * rules. + * + * @param url + * the URL + * @param kvPairs + * the list of key/value pairs + * @return string + */ + public static String addQueryParameters(String url, String... kvPairs) + throws MalformedInputException, UnmappableCharacterException { + String queryDelim = url.contains("?") ? "&" : "?"; + StringBuilder sb = new StringBuilder(url + queryDelim); + for (int i = 0; i < kvPairs.length; i += 2) { + if (i > 0) { + sb.append("&"); + } + sb.append(percentEncoder.encode(kvPairs[i])).append("=") + .append(percentEncoder.encode(kvPairs[i + 1])); + } + return sb.toString(); + } + + public static String addQueryParameters(String url, Map params) + throws MalformedInputException, UnmappableCharacterException { + String[] kvPairs = new String[params.size() * 2]; + int idx = 0; + for (String key : params.keySet()) { + kvPairs[idx] = key; + kvPairs[idx + 1] = params.get(key); + idx += 2; + } + return addQueryParameters(url, kvPairs); + } + + public static String addQueryString(String url, String queryString) { + String queryDelim = url.contains("?") ? "&" : "?"; + return url + queryDelim + queryString; + } + + /** + * Builds an OAuth header from the given list of header fields. All + * parameters starting in 'oauth_*' will be percent encoded. + * + * 
+     * String authHeader = OAuth.prepareOAuthHeader("realm", "http://example.com", "oauth_token", "x%y");
+     *
+ * + * which yields: + * + * 
+     * OAuth realm="http://example.com", oauth_token="x%25y"
+     *
+ * + * @param kvPairs + * the list of key/value pairs + * @return a string eligible to be used as an OAuth HTTP Authorization + * header. + */ + public static String prepareOAuthHeader(String... kvPairs) + throws MalformedInputException, UnmappableCharacterException { + StringBuilder sb = new StringBuilder("OAuth "); + for (int i = 0; i < kvPairs.length; i += 2) { + if (i > 0) { + sb.append(", "); + } + boolean isOAuthElem = kvPairs[i].startsWith("oauth_") + || kvPairs[i].startsWith("x_oauth_"); + String value = isOAuthElem ? percentEncoder.encode(kvPairs[i + 1]) : kvPairs[i + 1]; + sb.append(percentEncoder.encode(kvPairs[i])).append("=\"").append(value).append("\""); + } + return sb.toString(); + } + + public static HttpParameters oauthHeaderToParamsMap(String oauthHeader) + throws MalformedInputException, UnmappableCharacterException { + HttpParameters params = new HttpParameters(); + if (oauthHeader == null || !oauthHeader.startsWith("OAuth ")) { + return params; + } + String[] elements = oauthHeader.substring("OAuth ".length()).split(","); + for (String keyValuePair : elements) { + String[] keyValue = keyValuePair.split("="); + params.put(keyValue[0].trim(), keyValue[1].replace("\"", "").trim()); + } + return params; + } + + /** + * Helper method to concatenate a parameter and its value to a pair that can + * be used in an HTTP header. This method percent encodes both parts before + * joining them. + * + * @param name + * the OAuth parameter name, e.g. oauth_token + * @param value + * the OAuth parameter value, e.g. 'hello oauth' + * @return a name/value pair, e.g. oauth_token="hello%20oauth" + */ + public static String toHeaderElement(String name, String value) + throws MalformedInputException, UnmappableCharacterException { + return percentEncoder.encode(name) + "=\"" + percentEncoder.encode(value) + "\""; + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuthCommunicationException.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthCommunicationException.java new file mode 100644 index 0000000..d93c15c --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthCommunicationException.java @@ -0,0 +1,21 @@ +package org.xbib.net.oauth; + +@SuppressWarnings("serial") +public class OAuthCommunicationException extends OAuthException { + + private String responseBody; + + public OAuthCommunicationException(Exception cause) { + super("Communication with the service provider failed: " + + cause.getLocalizedMessage(), cause); + } + + public OAuthCommunicationException(String message, String responseBody) { + super(message); + this.responseBody = responseBody; + } + + public String getResponseBody() { + return responseBody; + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuthConsumer.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthConsumer.java new file mode 100644 index 0000000..da5a15b --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthConsumer.java @@ -0,0 +1,157 @@ +package org.xbib.net.oauth; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.oauth.sign.OAuthMessageSigner; +import org.xbib.net.oauth.sign.SigningStrategy; + +/** + *

+ * Exposes a simple interface to sign HTTP requests using a given OAuth token + * and secret. Refer to {@link OAuthProvider} how to retrieve a valid token and + * token secret. + *

+ * HTTP messages are signed as follows: + * + * 
+ * // exchange the arguments with the actual token/secret pair
+ * OAuthConsumer consumer = new DefaultOAuthConsumer("1234", "5678");
+ * URL url = new URL("http://example.com/protected.xml");
+ * HttpURLConnection request = (HttpURLConnection) url.openConnection();
+ * consumer.sign(request);
+ * request.connect();
+ *
+ * + */ +public interface OAuthConsumer { + + /** + * Sets the message signer that should be used to generate the OAuth + * signature. + * + * @param messageSigner + * the signer + */ + void setMessageSigner(OAuthMessageSigner messageSigner); + + /** + * Allows you to add parameters (typically OAuth parameters such as + * oauth_callback or oauth_verifier) which will go directly into the signer, + * i.e. you don't have to put them into the request first. The consumer's + * signing strategy will then take care of writing them to the + * correct part of the request before it is sent. This is useful if you want + * to pre-set custom OAuth parameters. Note that these parameters are + * expected to already be percent encoded -- they will be simply merged + * as-is. BE CAREFUL WITH THIS METHOD! Your service provider may decide + * to ignore any non-standard OAuth params when computing the signature. + * + * @param additionalParameters + * the parameters + */ + void setAdditionalParameters(HttpParameters additionalParameters); + + /** + * Defines which strategy should be used to write a signature to an HTTP + * request. + * + * @param signingStrategy + * the strategy + */ + void setSigningStrategy(SigningStrategy signingStrategy); + + /** + *

+ * Causes the consumer to always include the oauth_token parameter to be + * sent, even if blank. If you're seeing 401s during calls to + * {@link OAuthProvider#retrieveRequestToken}, try setting this to true. + *

+ * + * @param enable + * true or false + */ + void setSendEmptyTokens(boolean enable); + + /** + * Signs the given HTTP request by writing an OAuth signature (and other + * required OAuth parameters) to it. Where these parameters are written + * depends on the current {@link SigningStrategy}. + * + * @param request + * the request to sign + * @return the request object passed as an argument + * @throws OAuthMessageSignerException + * @throws OAuthExpectationFailedException + * @throws OAuthCommunicationException + */ + HttpRequest sign(HttpRequest request) throws OAuthMessageSignerException, + OAuthExpectationFailedException, OAuthCommunicationException; + + /** + *

+ * Signs the given HTTP request by writing an OAuth signature (and other + * required OAuth parameters) to it. Where these parameters are written + * depends on the current {@link SigningStrategy}. + *

+ * This method accepts HTTP library specific request objects; the consumer + * implementation must ensure that only those request types are passed which + * it supports. + * + * @param request + * the request to sign + * @return the request object passed as an argument + * @throws OAuthMessageSignerException + * @throws OAuthExpectationFailedException + * @throws OAuthCommunicationException + */ + HttpRequest sign(Object request) throws OAuthMessageSignerException, + OAuthExpectationFailedException, OAuthCommunicationException; + + /** + * "Signs" the given URL by appending all OAuth parameters to it which are + * required for message signing. The assumed HTTP method is GET. + * Essentially, this is equivalent to signing an HTTP GET request, but it + * can be useful if your application requires clickable links to protected + * resources, i.e. when your application does not have access to the actual + * request that is being sent. + * + * @param url + * the input URL. May have query parameters. + * @return the input URL, with all necessary OAuth parameters attached as a + * query string. Existing query parameters are preserved. + * @throws OAuthMessageSignerException + * @throws OAuthExpectationFailedException + * @throws OAuthCommunicationException + */ + String sign(String url) throws OAuthMessageSignerException, + OAuthExpectationFailedException, OAuthCommunicationException; + + /** + * Sets the OAuth token and token secret used for message signing. + * + * @param token + * the token + * @param tokenSecret + * the token secret + */ + void setTokenWithSecret(String token, String tokenSecret); + + String getToken(); + + String getTokenSecret(); + + String getConsumerKey(); + + String getConsumerSecret(); + + /** + * Returns all parameters collected from the HTTP request during message + * signing (this means the return value may be NULL before a call to + * {@link #sign}), plus all required OAuth parameters that were added + * because the request didn't contain them beforehand. In other words, this + * is the exact set of parameters that were used for creating the message + * signature. + * + * @return the request parameters used for message signing + */ + HttpParameters getRequestParameters(); +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuthException.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthException.java new file mode 100644 index 0000000..b15d139 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthException.java @@ -0,0 +1,17 @@ +package org.xbib.net.oauth; + +@SuppressWarnings("serial") +public abstract class OAuthException extends Exception { + + public OAuthException(String message) { + super(message); + } + + public OAuthException(Throwable cause) { + super(cause); + } + + public OAuthException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuthExpectationFailedException.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthExpectationFailedException.java new file mode 100644 index 0000000..f9d53ff --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthExpectationFailedException.java @@ -0,0 +1,9 @@ +package org.xbib.net.oauth; + +@SuppressWarnings("serial") +public class OAuthExpectationFailedException extends OAuthException { + + public OAuthExpectationFailedException(String message) { + super(message); + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuthMessageSignerException.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthMessageSignerException.java new file mode 100644 index 0000000..82797da --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthMessageSignerException.java @@ -0,0 +1,14 @@ +package org.xbib.net.oauth; + +@SuppressWarnings("serial") +public class OAuthMessageSignerException extends OAuthException { + + public OAuthMessageSignerException(String message) { + super(message); + } + + public OAuthMessageSignerException(Exception cause) { + super(cause); + } + +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuthNotAuthorizedException.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthNotAuthorizedException.java new file mode 100644 index 0000000..9d46d02 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthNotAuthorizedException.java @@ -0,0 +1,24 @@ +package org.xbib.net.oauth; + +@SuppressWarnings("serial") +public class OAuthNotAuthorizedException extends OAuthException { + + private static final String ERROR = "Authorization failed (server replied with a 401). " + + "This can happen if the consumer key was not correct or " + + "the signatures did not match."; + + private String responseBody; + + public OAuthNotAuthorizedException() { + super(ERROR); + } + + public OAuthNotAuthorizedException(String responseBody) { + super(ERROR); + this.responseBody = responseBody; + } + + public String getResponseBody() { + return responseBody; + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuthProvider.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthProvider.java new file mode 100644 index 0000000..baa6046 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthProvider.java @@ -0,0 +1,206 @@ +package org.xbib.net.oauth; + +import org.xbib.net.http.HttpParameters; + +/** + *

+ * Supplies an interface that can be used to retrieve request and access tokens + * from an OAuth 1.0(a) service provider. A provider object requires an + * {@link OAuthConsumer} to sign the token request message; after a token has + * been retrieved, the consumer is automatically updated with the token and the + * corresponding secret. + *

+ *

+ * To initiate the token exchange, create a new provider instance and configure + * it with the URLs the service provider exposes for requesting tokens and + * resource authorization, e.g.: + *

+ * + * 
+ * OAuthProvider provider = new DefaultOAuthProvider("http://twitter.com/oauth/request_token",
+ *         "http://twitter.com/oauth/access_token", "http://twitter.com/oauth/authorize");
+ *
+ *

+ * Depending on the HTTP library you use, you may need a different provider + * type, refer to the website documentation for how to do that. + *

+ *

+ * To receive a request token which the user must authorize, you invoke it using + * a consumer instance and a callback URL: + *

+ *

+ * + * 

+ * String url = provider.retrieveRequestToken(consumer, "http://www.example.com/callback");
+ *
+ * + *

+ *

+ * That url must be opened in a Web browser, where the user can grant access to + * the resources in question. If that succeeds, the service provider will + * redirect to the callback URL and append the blessed request token. + *

+ *

+ * That token must now be exchanged for an access token, as such: + *

+ *

+ * + * 

+ * provider.retrieveAccessToken(consumer, nullOrVerifierCode);
+ *
+ * + *

+ *

+ * where nullOrVerifierCode is either null if your provided a callback URL in + * the previous step, or the pin code issued by the service provider to the user + * if the request was out-of-band (cf. {@link OAuth#OUT_OF_BAND}. + *

+ *

+ * The consumer used during token handshakes is now ready for signing. + *

+ * + * @see OAuthProviderListener + */ +public interface OAuthProvider { + + /** + * Queries the service provider for a request token. + *

+ * Pre-conditions: the given {@link OAuthConsumer} must have a valid + * consumer key and consumer secret already set. + *

+ *

+ * Post-conditions: the given {@link OAuthConsumer} will have an + * unauthorized request token and token secret set. + *

+ * + * @param consumer + * the {@link OAuthConsumer} that should be used to sign the request + * @param callbackUrl + * Pass an actual URL if your app can receive callbacks and you want + * to get informed about the result of the authorization process. + * Pass OUT_OF_BAND if the service provider implements + * OAuth 1.0a and your app cannot receive callbacks. Pass null if the + * service provider implements OAuth 1.0 and your app cannot receive + * callbacks. Please note that some services (among them Twitter) + * will fail authorization if you pass a callback URL but register + * your application as a desktop app (which would only be able to + * handle OOB requests). + * @param customOAuthParams + * you can pass custom OAuth parameters here which will go directly + * into the signer, i.e. you don't have to put them into the request + * first. This is useful for pre-setting OAuth params for signing. + * Pass them sequentially in key/value order. + * @return The URL to which the user must be sent in order to authorize the + * consumer. It includes the unauthorized request token (and in the + * case of OAuth 1.0, the callback URL -- 1.0a clients send along + * with the token request). + * @throws OAuthMessageSignerException + * if signing the request failed + * @throws OAuthNotAuthorizedException + * if the service provider rejected the consumer + * @throws OAuthExpectationFailedException + * if required parameters were not correctly set by the consumer or + * service provider + * @throws OAuthCommunicationException + * if server communication failed + */ + String retrieveRequestToken(OAuthConsumer consumer, String callbackUrl, + String... customOAuthParams) throws OAuthMessageSignerException, + OAuthNotAuthorizedException, OAuthExpectationFailedException, + OAuthCommunicationException; + + /** + * Queries the service provider for an access token. + *

+ * Pre-conditions: the given {@link OAuthConsumer} must have a valid + * consumer key, consumer secret, authorized request token and token secret + * already set. + *

+ *

+ * Post-conditions: the given {@link OAuthConsumer} will have an + * access token and token secret set. + *

+ * + * @param consumer + * the {@link OAuthConsumer} that should be used to sign the request + * @param oauthVerifier + * NOTE: Only applies to service providers implementing OAuth + * 1.0a. Set to null if the service provider is still using OAuth + * 1.0. The verification code issued by the service provider + * after the the user has granted the consumer authorization. If the + * callback method provided in the previous step was + * OUT_OF_BAND, then you must ask the user for this + * value. If your app has received a callback, the verfication code + * was passed as part of that request instead. + * @param customOAuthParams + * you can pass custom OAuth parameters here which will go directly + * into the signer, i.e. you don't have to put them into the request + * first. This is useful for pre-setting OAuth params for signing. + * Pass them sequentially in key/value order. + * @throws OAuthMessageSignerException + * if signing the request failed + * @throws OAuthNotAuthorizedException + * if the service provider rejected the consumer + * @throws OAuthExpectationFailedException + * if required parameters were not correctly set by the consumer or + * service provider + * @throws OAuthCommunicationException + * if server communication failed + */ + void retrieveAccessToken(OAuthConsumer consumer, String oauthVerifier, + String... customOAuthParams) throws OAuthMessageSignerException, + OAuthNotAuthorizedException, OAuthExpectationFailedException, + OAuthCommunicationException; + + /** + * Any additional non-OAuth parameters returned in the response body of a + * token request can be obtained through this method. These parameters will + * be preserved until the next token request is issued. The return value is + * never null. + */ + HttpParameters getResponseParameters(); + + /** + * Subclasses must use this setter to preserve any non-OAuth query + * parameters contained in the server response. It's the caller's + * responsibility that any OAuth parameters be removed beforehand. + * + * @param parameters + * the map of query parameters served by the service provider in the + * token response + */ + void setResponseParameters(HttpParameters parameters); + + /** + * @param isOAuth10aProvider + * set to true if the service provider supports OAuth 1.0a. Note that + * you need only call this method if you reconstruct a provider + * object in between calls to retrieveRequestToken() and + * retrieveAccessToken() (i.e. if the object state isn't preserved). + * If instead those two methods are called on the same provider + * instance, this flag will be deducted automatically based on the + * server response during retrieveRequestToken(), so you can simply + * ignore this method. + */ + void setOAuth10a(boolean isOAuth10aProvider); + + /** + * @return true if the service provider supports OAuth 1.0a. Note that the + * value returned here is only meaningful after you have already + * performed the token handshake, otherwise there is no way to + * determine what version of the OAuth protocol the service provider + * implements. + */ + boolean isOAuth10a(); + + String getRequestTokenEndpointUrl(); + + String getAccessTokenEndpointUrl(); + + String getAuthorizationWebsiteUrl(); + + void setListener(OAuthProviderListener listener); + + void removeListener(OAuthProviderListener listener); +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/OAuthProviderListener.java b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthProviderListener.java new file mode 100644 index 0000000..26d3f61 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/OAuthProviderListener.java @@ -0,0 +1,47 @@ +package org.xbib.net.oauth; + +import org.xbib.net.http.HttpRequest; +import org.xbib.net.http.HttpResponse; + +/** + * Provides hooks into the token request handling procedure executed by + * {@link OAuthProvider}. + * + */ +public interface OAuthProviderListener { + + /** + * Called after the request has been created and default headers added, but + * before the request has been signed. + * + * @param request + * the request to be sent + * @throws Exception + */ + void prepareRequest(HttpRequest request) throws Exception; + + /** + * Called after the request has been signed, but before it's being sent. + * + * @param request + * the request to be sent + * @throws Exception + */ + void prepareSubmission(HttpRequest request) throws Exception; + + /** + * Called when the server response has been received. You can implement this + * to manually handle the response data. + * + * @param request + * the request that was sent + * @param response + * the response that was received + * @return returning true means you have handled the response, and the + * provider will return immediately. Return false to let the event + * propagate and let the provider execute its default response + * handling. + * @throws Exception + */ + boolean onResponseReceived(HttpRequest request, HttpResponse response) throws Exception; +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/sign/AuthorizationHeaderSigningStrategy.java b/net-oauth/src/main/java/org/xbib/net/oauth/sign/AuthorizationHeaderSigningStrategy.java new file mode 100644 index 0000000..49e146b --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/sign/AuthorizationHeaderSigningStrategy.java @@ -0,0 +1,42 @@ +package org.xbib.net.oauth.sign; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.oauth.OAuth; + +import java.nio.charset.MalformedInputException; +import java.nio.charset.UnmappableCharacterException; +import java.util.Iterator; + +/** + * Writes to the HTTP Authorization header field. + */ +public class AuthorizationHeaderSigningStrategy implements SigningStrategy { + + @Override + public String writeSignature(String signature, HttpRequest request, + HttpParameters requestParameters) throws MalformedInputException, UnmappableCharacterException { + StringBuilder sb = new StringBuilder(); + sb.append("OAuth "); + // add the realm parameter, if any + if (requestParameters.containsKey("realm")) { + sb.append(requestParameters.getAsHeaderElement("realm")); + sb.append(", "); + } + // add all (x_)oauth parameters + HttpParameters oauthParams = requestParameters.getOAuthParameters(); + oauthParams.put(OAuth.OAUTH_SIGNATURE, signature, true); + Iterator iterator = oauthParams.keySet().iterator(); + while (iterator.hasNext()) { + String key = iterator.next(); + sb.append(oauthParams.getAsHeaderElement(key)); + if (iterator.hasNext()) { + sb.append(", "); + } + } + String header = sb.toString(); + request.setHeader(OAuth.HTTP_AUTHORIZATION_HEADER, header); + return header; + } + +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/sign/HmacSha1MessageSigner.java b/net-oauth/src/main/java/org/xbib/net/oauth/sign/HmacSha1MessageSigner.java new file mode 100644 index 0000000..b386559 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/sign/HmacSha1MessageSigner.java @@ -0,0 +1,45 @@ +package org.xbib.net.oauth.sign; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.oauth.OAuth; +import org.xbib.net.oauth.OAuthMessageSignerException; + +import java.io.UnsupportedEncodingException; +import java.nio.charset.MalformedInputException; +import java.nio.charset.UnmappableCharacterException; +import java.security.GeneralSecurityException; + +import javax.crypto.Mac; +import javax.crypto.SecretKey; +import javax.crypto.spec.SecretKeySpec; + +@SuppressWarnings("serial") +public class HmacSha1MessageSigner extends OAuthMessageSigner { + + private static final String MAC_NAME = "HmacSHA1"; + + @Override + public String getSignatureMethod() { + return "HMAC-SHA1"; + } + + @Override + public String sign(HttpRequest request, HttpParameters requestParams) + throws OAuthMessageSignerException { + try { + String keyString = OAuth.percentEncoder.encode(getConsumerSecret()) + '&' + + OAuth.percentEncoder.encode(getTokenSecret()); + byte[] keyBytes = keyString.getBytes(OAuth.ENCODING); + SecretKey key = new SecretKeySpec(keyBytes, MAC_NAME); + Mac mac = Mac.getInstance(MAC_NAME); + mac.init(key); + String sbs = new SignatureBaseString(request, requestParams).generate(); + byte[] text = sbs.getBytes(OAuth.ENCODING); + return base64Encode(mac.doFinal(text)).trim(); + } catch (GeneralSecurityException | UnsupportedEncodingException | + MalformedInputException | UnmappableCharacterException e) { + throw new OAuthMessageSignerException(e); + } + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/sign/HmacSha256MessageSigner.java b/net-oauth/src/main/java/org/xbib/net/oauth/sign/HmacSha256MessageSigner.java new file mode 100644 index 0000000..2d756f4 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/sign/HmacSha256MessageSigner.java @@ -0,0 +1,45 @@ +package org.xbib.net.oauth.sign; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.oauth.OAuth; +import org.xbib.net.oauth.OAuthMessageSignerException; + +import java.io.UnsupportedEncodingException; +import java.nio.charset.MalformedInputException; +import java.nio.charset.UnmappableCharacterException; +import java.security.GeneralSecurityException; + +import javax.crypto.Mac; +import javax.crypto.SecretKey; +import javax.crypto.spec.SecretKeySpec; + +@SuppressWarnings("serial") +public class HmacSha256MessageSigner extends OAuthMessageSigner { + + private static final String MAC_NAME = "HmacSHA256"; + + @Override + public String getSignatureMethod() { + return "HMAC-SHA256"; + } + + @Override + public String sign(HttpRequest request, HttpParameters requestParams) + throws OAuthMessageSignerException { + try { + String keyString = OAuth.percentEncoder.encode(getConsumerSecret()) + '&' + + OAuth.percentEncoder.encode(getTokenSecret()); + byte[] keyBytes = keyString.getBytes(OAuth.ENCODING); + SecretKey key = new SecretKeySpec(keyBytes, MAC_NAME); + Mac mac = Mac.getInstance(MAC_NAME); + mac.init(key); + String sbs = new SignatureBaseString(request, requestParams).generate(); + byte[] text = sbs.getBytes(OAuth.ENCODING); + return base64Encode(mac.doFinal(text)).trim(); + } catch (GeneralSecurityException | UnsupportedEncodingException | + MalformedInputException| UnmappableCharacterException e) { + throw new OAuthMessageSignerException(e); + } + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/sign/OAuthMessageSigner.java b/net-oauth/src/main/java/org/xbib/net/oauth/sign/OAuthMessageSigner.java new file mode 100644 index 0000000..35f8445 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/sign/OAuthMessageSigner.java @@ -0,0 +1,54 @@ +package org.xbib.net.oauth.sign; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.oauth.OAuthMessageSignerException; + +import java.util.Base64; + + +public abstract class OAuthMessageSigner { + + private Base64.Encoder base64Encoder; + + private Base64.Decoder base64Decoder; + + private String consumerSecret; + + private String tokenSecret; + + public OAuthMessageSigner() { + this.base64Encoder = Base64.getEncoder(); + this.base64Decoder = Base64.getDecoder(); + } + + public abstract String sign(HttpRequest request, HttpParameters requestParameters) + throws OAuthMessageSignerException; + + public abstract String getSignatureMethod(); + + public String getConsumerSecret() { + return consumerSecret; + } + + public String getTokenSecret() { + return tokenSecret; + } + + public void setConsumerSecret(String consumerSecret) { + this.consumerSecret = consumerSecret; + } + + public void setTokenSecret(String tokenSecret) { + this.tokenSecret = tokenSecret; + } + + protected byte[] decodeBase64(String s) { + return base64Decoder.decode(s.getBytes()); + } + + protected String base64Encode(byte[] b) { + return new String(base64Encoder.encode(b)); + } + +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/sign/PlainTextMessageSigner.java b/net-oauth/src/main/java/org/xbib/net/oauth/sign/PlainTextMessageSigner.java new file mode 100644 index 0000000..ef280c3 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/sign/PlainTextMessageSigner.java @@ -0,0 +1,29 @@ +package org.xbib.net.oauth.sign; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.oauth.OAuth; +import org.xbib.net.oauth.OAuthMessageSignerException; + +import java.nio.charset.MalformedInputException; +import java.nio.charset.UnmappableCharacterException; + +@SuppressWarnings("serial") +public class PlainTextMessageSigner extends OAuthMessageSigner { + + @Override + public String getSignatureMethod() { + return "PLAINTEXT"; + } + + @Override + public String sign(HttpRequest request, HttpParameters requestParams) + throws OAuthMessageSignerException { + try { + return OAuth.percentEncoder.encode(getConsumerSecret()) + '&' + + OAuth.percentEncoder.encode(getTokenSecret()); + } catch (MalformedInputException | UnmappableCharacterException e) { + throw new OAuthMessageSignerException(e); + } + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/sign/QueryStringSigningStrategy.java b/net-oauth/src/main/java/org/xbib/net/oauth/sign/QueryStringSigningStrategy.java new file mode 100644 index 0000000..ddf0de2 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/sign/QueryStringSigningStrategy.java @@ -0,0 +1,41 @@ +package org.xbib.net.oauth.sign; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.oauth.OAuth; + +import java.nio.charset.MalformedInputException; +import java.nio.charset.UnmappableCharacterException; +import java.util.Iterator; + +/** + * Writes to a URL query string. Note that this currently ONLY works + * when signing a URL directly, not with HTTP request objects. That's + * because most HTTP request implementations do not allow the client to change + * the URL once the request has been instantiated, so there is no way to append + * parameters to it. + */ +public class QueryStringSigningStrategy implements SigningStrategy { + + @Override + public String writeSignature(String signature, HttpRequest request, + HttpParameters requestParameters) + throws MalformedInputException, UnmappableCharacterException { + // add all (x_)oauth parameters + HttpParameters oauthParams = requestParameters.getOAuthParameters(); + oauthParams.put(OAuth.OAUTH_SIGNATURE, signature, true); + Iterator iterator = oauthParams.keySet().iterator(); + // add the first query parameter (we always have at least the signature) + String firstKey = iterator.next(); + StringBuilder sb = new StringBuilder(OAuth.addQueryString(request.getRequestUrl(), + oauthParams.getAsQueryString(firstKey))); + while (iterator.hasNext()) { + sb.append("&"); + String key = iterator.next(); + sb.append(oauthParams.getAsQueryString(key)); + } + String signedUrl = sb.toString(); + request.setRequestUrl(signedUrl); + return signedUrl; + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/sign/SignatureBaseString.java b/net-oauth/src/main/java/org/xbib/net/oauth/sign/SignatureBaseString.java new file mode 100644 index 0000000..fa64c3b --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/sign/SignatureBaseString.java @@ -0,0 +1,96 @@ +package org.xbib.net.oauth.sign; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; +import org.xbib.net.oauth.OAuth; +import org.xbib.net.oauth.OAuthMessageSignerException; + +import java.io.IOException; +import java.net.URI; +import java.net.URISyntaxException; +import java.util.Iterator; + +public class SignatureBaseString { + + private final HttpRequest request; + + private final HttpParameters requestParameters; + + /** + * Constructs a new instance that will operate on the given request + * object and parameter set. + * + * @param request the HTTP request + * @param requestParameters the set of request parameters from the Authorization header, query + * string and form body + */ + public SignatureBaseString(HttpRequest request, HttpParameters requestParameters) { + this.request = request; + this.requestParameters = requestParameters; + } + + /** + * Builds the signature base string from the data this instance was + * configured with. + * + * @return the signature base string + * @throws OAuthMessageSignerException + */ + public String generate() throws OAuthMessageSignerException { + try { + String normalizedUrl = normalizeRequestUrl(); + String normalizedParams = normalizeRequestParameters(); + return request.getMethod() + '&' + OAuth.percentEncoder.encode(normalizedUrl) + '&' + + OAuth.percentEncoder.encode(normalizedParams); + } catch (URISyntaxException | IOException e) { + throw new OAuthMessageSignerException(e); + } + } + + public String normalizeRequestUrl() throws URISyntaxException { + URI uri = new URI(request.getRequestUrl()); + String scheme = uri.getScheme().toLowerCase(); + String authority = uri.getAuthority().toLowerCase(); + boolean dropPort = (scheme.equals("http") && uri.getPort() == 80) + || (scheme.equals("https") && uri.getPort() == 443); + if (dropPort) { + // find the last : in the authority + int index = authority.lastIndexOf(":"); + if (index >= 0) { + authority = authority.substring(0, index); + } + } + String path = uri.getRawPath(); + if (path == null || path.length() <= 0) { + path = "/"; // conforms to RFC 2616 section 3.2.2 + } + // we know that there is no query and no fragment here. + return scheme + "://" + authority + path; + } + + /** + * Normalizes the set of request parameters this instance was configured + * with, as per OAuth spec section 9.1.1. + * + * @return the normalized params string + * @throws IOException + */ + public String normalizeRequestParameters() throws IOException { + if (requestParameters == null) { + return ""; + } + StringBuilder sb = new StringBuilder(); + Iterator iter = requestParameters.keySet().iterator(); + for (int i = 0; iter.hasNext(); i++) { + String param = iter.next(); + if (OAuth.OAUTH_SIGNATURE.equals(param) || "realm".equals(param)) { + continue; + } + if (i > 0) { + sb.append("&"); + } + sb.append(requestParameters.getAsQueryString(param, false)); + } + return sb.toString(); + } +} diff --git a/net-oauth/src/main/java/org/xbib/net/oauth/sign/SigningStrategy.java b/net-oauth/src/main/java/org/xbib/net/oauth/sign/SigningStrategy.java new file mode 100644 index 0000000..60e39b0 --- /dev/null +++ b/net-oauth/src/main/java/org/xbib/net/oauth/sign/SigningStrategy.java @@ -0,0 +1,37 @@ +package org.xbib.net.oauth.sign; + +import org.xbib.net.http.HttpParameters; +import org.xbib.net.http.HttpRequest; + +import java.nio.charset.MalformedInputException; +import java.nio.charset.UnmappableCharacterException; + +/** + *

+ * Defines how an OAuth signature string is written to a request. + *

+ *

+ * Unlike {@link OAuthMessageSigner}, which is concerned with how to + * generate a signature, this class is concered with where to write it + * (e.g. HTTP header or query string). + *

+ */ +public interface SigningStrategy { + + /** + * Writes an OAuth signature and all remaining required parameters to an + * HTTP message. + * + * @param signature + * the signature to write + * @param request + * the request to sign + * @param requestParameters + * the request parameters + * @return whatever has been written to the request, e.g. an Authorization + * header field + */ + String writeSignature(String signature, HttpRequest request, HttpParameters requestParameters) + throws MalformedInputException, UnmappableCharacterException; + +} diff --git a/net-url/src/main/java/org/xbib/net/QueryParameters.java b/net-url/src/main/java/org/xbib/net/QueryParameters.java index 30d83d8..5287cfa 100644 --- a/net-url/src/main/java/org/xbib/net/QueryParameters.java +++ b/net-url/src/main/java/org/xbib/net/QueryParameters.java @@ -5,7 +5,7 @@ import java.util.List; import java.util.stream.Collectors; /** - * Query parameters. + * Query parameter list, of limited size. Default is 1024 pairs. */ public class QueryParameters extends ArrayList> { diff --git a/net-url/src/main/java/org/xbib/net/URL.java b/net-url/src/main/java/org/xbib/net/URL.java index 3985b6f..88161f3 100755 --- a/net-url/src/main/java/org/xbib/net/URL.java +++ b/net-url/src/main/java/org/xbib/net/URL.java @@ -864,6 +864,12 @@ public class URL implements Comparable { return this; } + public Builder resetQueryParams() { + queryParams.clear(); + query = null; + return this; + } + /** * Add a query parameter. Query parameters will be encoded in the order added. * diff --git a/settings.gradle b/settings.gradle index a32c64d..925906e 100644 --- a/settings.gradle +++ b/settings.gradle @@ -1,3 +1,4 @@ rootProject.name = name include 'net-url' +include 'net-http'