HttpsURLConnection

Class Overview

An HttpURLConnection for HTTPS (RFC 2818). A connected HttpsURLConnection allows access to the negotiated cipher suite, the server certificate chain, and the client certificate chain if any.

Providing an application specific X509TrustManager

If an application wants to trust Certificate Authority (CA) certificates that are not part of the system, it should specify its own X509TrustManager via a SSLSocketFactory set on the HttpsURLConnection. The X509TrustManager can be created based on a KeyStore using a TrustManagerFactory to supply trusted CA certificates. Note that self-signed certificates are effectively their own CA and can be trusted by including them in a KeyStore.

For example, to trust a set of certificates specified by a KeyStore:

   KeyStore keyStore = ...;
   TrustManagerFactory tmf = TrustManagerFactory.getInstance("X509");
   tmf.init(keyStore);

   SSLContext context = SSLContext.getInstance("TLS");
   context.init(null, tmf.getTrustManagers(), null);

   URL url = new URL("https://www.example.com/");
   HttpsURLConnection urlConnection = (HttpsURLConnection) url.openConnection();
   urlConnection.setSSLSocketFactory(context.getSocketFactory());
   InputStream in = urlConnection.getInputStream();
 

It is possible to implement X509TrustManager directly instead of using one created by a TrustManagerFactory. While this is straightforward in the insecure case of allowing all certificate chains to pass verification, writing a proper implementation will usually want to take advantage of CertPathValidator. In general, it might be better to write a custom KeyStore implementation to pass to the TrustManagerFactory than to try and write a custom X509TrustManager.

Providing an application specific X509KeyManager

A custom X509KeyManager can be used to supply a client certificate and its associated private key to authenticate a connection to the server. The X509KeyManager can be created based on a KeyStore using a KeyManagerFactory.

For example, to supply client certificates from a KeyStore:

   KeyStore keyStore = ...;
   KeyManagerFactory kmf = KeyManagerFactory.getInstance("X509");
   kmf.init(keyStore);

   SSLContext context = SSLContext.getInstance("TLS");
   context.init(kmf.getKeyManagers(), null, null);

   URL url = new URL("https://www.example.com/");
   HttpsURLConnection urlConnection = (HttpsURLConnection) url.openConnection();
   urlConnection.setSSLSocketFactory(context.getSocketFactory());
   InputStream in = urlConnection.getInputStream();
 

A X509KeyManager can also be implemented directly. This can allow an application to return a certificate and private key from a non-KeyStore source or to specify its own logic for selecting a specific credential to use when many may be present in a single KeyStore.

TLS Intolerance Support

This class attempts to create secure connections using common TLS extensions and SSL deflate compression. Should that fail, the connection will be retried with SSLv3 only.

Summary

[Expand] Inherited Constants

From class java.net.HttpURLConnection int HTTP_ACCEPTED Numeric status code, 202: Accepted int HTTP_BAD_GATEWAY Numeric status code, 502: Bad Gateway int HTTP_BAD_METHOD Numeric status code, 405: Bad Method int HTTP_BAD_REQUEST Numeric status code, 400: Bad Request int HTTP_CLIENT_TIMEOUT Numeric status code, 408: Client Timeout int HTTP_CONFLICT Numeric status code, 409: Conflict int HTTP_CREATED Numeric status code, 201: Created int HTTP_ENTITY_TOO_LARGE Numeric status code, 413: Entity too large int HTTP_FORBIDDEN Numeric status code, 403: Forbidden int HTTP_GATEWAY_TIMEOUT Numeric status code, 504: Gateway timeout int HTTP_GONE Numeric status code, 410: Gone int HTTP_INTERNAL_ERROR Numeric status code, 500: Internal error int HTTP_LENGTH_REQUIRED Numeric status code, 411: Length required int HTTP_MOVED_PERM Numeric status code, 301 Moved permanently int HTTP_MOVED_TEMP Numeric status code, 302: Moved temporarily int HTTP_MULT_CHOICE Numeric status code, 300: Multiple choices int HTTP_NOT_ACCEPTABLE Numeric status code, 406: Not acceptable int HTTP_NOT_AUTHORITATIVE Numeric status code, 203: Not authoritative int HTTP_NOT_FOUND Numeric status code, 404: Not found int HTTP_NOT_IMPLEMENTED Numeric status code, 501: Not implemented int HTTP_NOT_MODIFIED Numeric status code, 304: Not modified int HTTP_NO_CONTENT Numeric status code, 204: No content int HTTP_OK Numeric status code, 200: OK int HTTP_PARTIAL Numeric status code, 206: Partial int HTTP_PAYMENT_REQUIRED Numeric status code, 402: Payment required int HTTP_PRECON_FAILED Numeric status code, 412: Precondition failed int HTTP_PROXY_AUTH Numeric status code, 407: Proxy authentication required int HTTP_REQ_TOO_LONG Numeric status code, 414: Request too long int HTTP_RESET Numeric status code, 205: Reset int HTTP_SEE_OTHER Numeric status code, 303: See other int HTTP_SERVER_ERROR This constant is deprecated. Use HTTP_INTERNAL_ERROR int HTTP_UNAUTHORIZED Numeric status code, 401: Unauthorized int HTTP_UNAVAILABLE Numeric status code, 503: Unavailable int HTTP_UNSUPPORTED_TYPE Numeric status code, 415: Unsupported type int HTTP_USE_PROXY Numeric status code, 305: Use proxy. int HTTP_VERSION Numeric status code, 505: Version not supported

Fields
protected HostnameVerifier	hostnameVerifier	The host name verifier used by this connection.

[Expand] Inherited Fields
From class java.net.HttpURLConnection protected int chunkLength If the HTTP chunked encoding is enabled this parameter defines the chunk-length. protected int fixedContentLength If using HTTP fixed-length streaming mode this parameter defines the fixed length of content. protected boolean instanceFollowRedirects Flag to define whether the protocol will automatically follow redirects or not. protected String method The HTTP request method of this HttpURLConnection. protected int responseCode The status code of the response obtained from the HTTP request. protected String responseMessage The HTTP response message which corresponds to the response code.
From class java.net.URLConnection protected boolean allowUserInteraction Specifies whether this URLConnection allows user interaction as it is needed for authentication purposes. protected boolean connected Specifies whether this URLConnection is already connected to the remote resource. protected boolean doInput Specifies whether this URLConnection allows receiving data. protected boolean doOutput Specifies whether this URLConnection allows sending data. protected long ifModifiedSince The data must be modified more recently than this time in milliseconds since January 1, 1970, GMT to be transmitted. protected URL url The URL which represents the remote target of this URLConnection. protected boolean useCaches Specifies whether the using of caches is enabled or the data has to be recent for every request.

Protected Constructors
	HttpsURLConnection(URL url) Creates a new HttpsURLConnection with the specified URL.

Public Methods
abstract String	getCipherSuite() Returns the name of the cipher suite negotiated during the SSL handshake.
static HostnameVerifier	getDefaultHostnameVerifier() Returns the default hostname verifier.
static SSLSocketFactory	getDefaultSSLSocketFactory() Returns the default SSL socket factory for new instances.
HostnameVerifier	getHostnameVerifier() Returns the hostname verifier used by this instance.
abstract Certificate[]	getLocalCertificates() Returns the list of local certificates used during the handshake.
Principal	getLocalPrincipal() Returns the Principal used to identify the local host during the handshake.
Principal	getPeerPrincipal() Returns the Principal identifying the peer.
SSLSocketFactory	getSSLSocketFactory() Returns the SSL socket factory used by this instance.
abstract Certificate[]	getServerCertificates() Return the list of certificates identifying the peer during the handshake.
static void	setDefaultHostnameVerifier(HostnameVerifier v) Sets the default hostname verifier to be used by new instances.
static void	setDefaultSSLSocketFactory(SSLSocketFactory sf) Sets the default SSL socket factory to be used by new instances.
void	setHostnameVerifier(HostnameVerifier v) Sets the hostname verifier for this instance.
void	setSSLSocketFactory(SSLSocketFactory sf) Sets the SSL socket factory for this instance.

[Expand] Inherited Methods
From class java.net.HttpURLConnection abstract void disconnect() Releases this connection so that its resources may be either reused or closed. String getContentEncoding() Returns the encoding used to transmit the response body over the network. InputStream getErrorStream() Returns an input stream from the server in the case of an error such as the requested file has not been found on the remote server. static boolean getFollowRedirects() Returns the value of followRedirects which indicates if this connection follows a different URL redirected by the server. long getHeaderFieldDate(String field, long defaultValue) Returns the date value in milliseconds since 01.01.1970, 00:00h corresponding to the header field field. boolean getInstanceFollowRedirects() Returns whether this connection follows redirects. Permission getPermission() Returns the permission object (in this case SocketPermission) with the host and the port number as the target name and "resolve, connect" as the action list. String getRequestMethod() Returns the request method which will be used to make the request to the remote HTTP server. int getResponseCode() Returns the response code returned by the remote HTTP server. String getResponseMessage() Returns the response message returned by the remote HTTP server. void setChunkedStreamingMode(int chunkLength) Stream a request body whose length is not known in advance. void setFixedLengthStreamingMode(int contentLength) If the length of a HTTP request body is known ahead, sets fixed length to enable streaming without buffering. static void setFollowRedirects(boolean auto) Sets the flag of whether this connection will follow redirects returned by the remote server. void setInstanceFollowRedirects(boolean followRedirects) Sets whether this connection follows redirects. void setRequestMethod(String method) Sets the request command which will be sent to the remote HTTP server. abstract boolean usingProxy() Returns whether this connection uses a proxy server or not.
From class java.net.URLConnection void addRequestProperty(String field, String newValue) Adds the given property to the request header. abstract void connect() Opens a connection to the resource. boolean getAllowUserInteraction() Returns the option value which indicates whether user interaction is allowed on this URLConnection. int getConnectTimeout() Returns the connect timeout in milliseconds, or 0 if connect attempts never timeout. Object getContent() Returns an object representing the content of the resource this URLConnection is connected to. Object getContent(Class[] types) Returns an object representing the content of the resource this URLConnection is connected to. String getContentEncoding() Returns the content encoding type specified by the response header field content-encoding or null if this field is not set. int getContentLength() Returns the content length in bytes specified by the response header field content-length or -1 if this field is not set. String getContentType() Returns the MIME-type of the content specified by the response header field content-type or null if type is unknown. long getDate() Returns the timestamp when this response has been sent as a date in milliseconds since January 1, 1970 GMT or 0 if this timestamp is unknown. static boolean getDefaultAllowUserInteraction() Returns the default setting whether this connection allows user interaction. static String getDefaultRequestProperty(String field) This method is deprecated. Use getRequestProperty(String) boolean getDefaultUseCaches() Returns the default setting whether this connection allows using caches. boolean getDoInput() Returns the value of the option doInput which specifies whether this connection allows to receive data. boolean getDoOutput() Returns the value of the option doOutput which specifies whether this connection allows to send data. long getExpiration() Returns the timestamp when this response will be expired in milliseconds since January 1, 1970 GMT or 0 if this timestamp is unknown. static FileNameMap getFileNameMap() Returns the table which is used by all URLConnection instances to determine the MIME-type according to a file extension. String getHeaderField(String key) Returns the value of the header field specified by key or null if there is no field with this name. String getHeaderField(int pos) Returns the header value at the field position pos or null if the header has fewer than pos fields. long getHeaderFieldDate(String field, long defaultValue) Returns the specified header value as a date in milliseconds since January 1, 1970 GMT. int getHeaderFieldInt(String field, int defaultValue) Returns the specified header value as a number. String getHeaderFieldKey(int posn) Returns the name of the header field at the given position posn or null if there are fewer than posn fields. Map<String, List<String>> getHeaderFields() Returns an unmodifiable map of the response-header fields and values. long getIfModifiedSince() Returns the point of time since when the data must be modified to be transmitted. InputStream getInputStream() Returns an InputStream for reading data from the resource pointed by this URLConnection. long getLastModified() Returns the value of the response header field last-modified or 0 if this value is not set. OutputStream getOutputStream() Returns an OutputStream for writing data to this URLConnection. Permission getPermission() Returns a Permission object representing all needed permissions to open this connection. int getReadTimeout() Returns the read timeout in milliseconds, or 0 if reads never timeout. Map<String, List<String>> getRequestProperties() Returns an unmodifiable map of general request properties used by this connection. String getRequestProperty(String field) Returns the value of the request header property specified by {code field} or null if there is no field with this name. URL getURL() Returns the URL represented by this URLConnection. boolean getUseCaches() Returns the value of the flag which specifies whether this URLConnection allows to use caches. static String guessContentTypeFromName(String url) Determines the MIME-type of the given resource url by resolving the filename extension with the internal FileNameMap. static String guessContentTypeFromStream(InputStream is) Determines the MIME-type of the resource represented by the input stream is by reading its first few characters. void setAllowUserInteraction(boolean newValue) Sets the flag indicating whether this connection allows user interaction or not. void setConnectTimeout(int timeoutMillis) Sets the maximum time to wait for a connect to complete before giving up. synchronized static void setContentHandlerFactory(ContentHandlerFactory contentFactory) Sets the internally used content handler factory. static void setDefaultAllowUserInteraction(boolean allows) Sets the default value for the flag indicating whether this connection allows user interaction or not. static void setDefaultRequestProperty(String field, String value) This method is deprecated. Use setRequestProperty(String, String). void setDefaultUseCaches(boolean newValue) Sets the default value for the flag indicating whether this connection allows to use caches. void setDoInput(boolean newValue) Sets the flag indicating whether this URLConnection allows input. void setDoOutput(boolean newValue) Sets the flag indicating whether this URLConnection allows output. static void setFileNameMap(FileNameMap map) Sets the internal map which is used by all URLConnection instances to determine the MIME-type according to a filename extension. void setIfModifiedSince(long newValue) Sets the point of time since when the data must be modified to be transmitted. void setReadTimeout(int timeoutMillis) Sets the maximum time to wait for an input stream read to complete before giving up. void setRequestProperty(String field, String newValue) Sets the value of the specified request header field. void setUseCaches(boolean newValue) Sets the flag indicating whether this connection allows to use caches or not. String toString() Returns the string representation containing the name of this class and the URL.
From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.