Bug 767516 - Rename: s/SSLConnect/ProxyConnect/g r=mcmanus
☠☠ backed out by 51cff2123f45 ☠ ☠
authorJason Duell <jduell.mcbugs@gmail.com>
Mon, 25 Jun 2012 12:48:50 -0700
changeset 97593 d45ca69b67a3bb9edd2f9495d8db468b384c3eff
parent 97592 4ff98d3e4d8d00eedb0b318c80744e9cb5ad362c
child 97594 2ae1e57c5851d530ccd43c80e9cf64bd67389cc5
push id11123
push userjduell@mozilla.com
push dateMon, 25 Jun 2012 19:49:01 +0000
treeherdermozilla-inbound@d45ca69b67a3 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmcmanus
bugs767516
milestone16.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 767516 - Rename: s/SSLConnect/ProxyConnect/g r=mcmanus
netwerk/protocol/http/NullHttpTransaction.cpp
netwerk/protocol/http/NullHttpTransaction.h
netwerk/protocol/http/SpdySession2.cpp
netwerk/protocol/http/SpdySession3.cpp
netwerk/protocol/http/nsAHttpTransaction.h
netwerk/protocol/http/nsHttpChannel.cpp
netwerk/protocol/http/nsHttpChannel.h
netwerk/protocol/http/nsHttpConnection.cpp
netwerk/protocol/http/nsHttpPipeline.cpp
netwerk/protocol/http/nsHttpTransaction.cpp
netwerk/protocol/http/nsHttpTransaction.h
netwerk/protocol/http/nsIHttpAuthManager.idl
--- a/netwerk/protocol/http/NullHttpTransaction.cpp
+++ b/netwerk/protocol/http/NullHttpTransaction.cpp
@@ -147,17 +147,17 @@ NullHttpTransaction::RequestHead()
 nsresult
 NullHttpTransaction::TakeSubTransactions(
   nsTArray<nsRefPtr<nsAHttpTransaction> > &outTransactions)
 {
   return NS_ERROR_NOT_IMPLEMENTED;
 }
 
 void
-NullHttpTransaction::SetSSLConnectFailed()
+NullHttpTransaction::SetProxyConnectFailed()
 {
 }
 
 void
 NullHttpTransaction::Close(nsresult reason)
 {
   mStatus = reason;
   mConnection = nsnull;
--- a/netwerk/protocol/http/NullHttpTransaction.h
+++ b/netwerk/protocol/http/NullHttpTransaction.h
@@ -13,17 +13,17 @@
 #include "nsIEventTarget.h"
 #include "nsHttpConnectionInfo.h"
 #include "nsHttpRequestHead.h"
 #include "mozilla/Attributes.h"
 
 // This is the minimal nsAHttpTransaction implementation. A NullHttpTransaction
 // can be used to drive connection level semantics (such as SSL handshakes
 // tunnels) so that a nsHttpConnection becomes fully established in
-// anticiation of a real transaction needing to use it soon.
+// anticipation of a real transaction needing to use it soon.
 
 namespace mozilla { namespace net {
 
 class NullHttpTransaction MOZ_FINAL : public nsAHttpTransaction
 {
 public:
   NS_DECL_ISUPPORTS
   NS_DECL_NSAHTTPTRANSACTION
--- a/netwerk/protocol/http/SpdySession2.cpp
+++ b/netwerk/protocol/http/SpdySession2.cpp
@@ -2156,19 +2156,19 @@ void
 SpdySession2::GetSecurityCallbacks(nsIInterfaceRequestor **,
                                   nsIEventTarget **)
 {
   // This is unexpected
   NS_ABORT_IF_FALSE(false, "SpdySession2::GetSecurityCallbacks()");
 }
 
 void
-SpdySession2::SetSSLConnectFailed()
+SpdySession2::SetProxyConnectFailed()
 {
-  NS_ABORT_IF_FALSE(false, "SpdySession2::SetSSLConnectFailed()");
+  NS_ABORT_IF_FALSE(false, "SpdySession2::SetProxyConnectFailed()");
 }
 
 bool
 SpdySession2::IsDone()
 {
   return !mStreamTransactionHash.Count();
 }
 
--- a/netwerk/protocol/http/SpdySession3.cpp
+++ b/netwerk/protocol/http/SpdySession3.cpp
@@ -2213,19 +2213,19 @@ void
 SpdySession3::GetSecurityCallbacks(nsIInterfaceRequestor **,
                                   nsIEventTarget **)
 {
   // This is unexpected
   NS_ABORT_IF_FALSE(false, "SpdySession3::GetSecurityCallbacks()");
 }
 
 void
-SpdySession3::SetSSLConnectFailed()
+SpdySession3::SetProxyConnectFailed()
 {
-  NS_ABORT_IF_FALSE(false, "SpdySession3::SetSSLConnectFailed()");
+  NS_ABORT_IF_FALSE(false, "SpdySession3::SetProxyConnectFailed()");
 }
 
 bool
 SpdySession3::IsDone()
 {
   return !mStreamTransactionHash.Count();
 }
 
--- a/netwerk/protocol/http/nsAHttpTransaction.h
+++ b/netwerk/protocol/http/nsAHttpTransaction.h
@@ -58,18 +58,18 @@ public:
 
     // called to write response data to the transaction.
     virtual nsresult WriteSegments(nsAHttpSegmentWriter *writer,
                                    PRUint32 count, PRUint32 *countWritten) = 0;
 
     // called to close the transaction
     virtual void Close(nsresult reason) = 0;
 
-    // called to indicate a failure at the SSL setup level
-    virtual void SetSSLConnectFailed() = 0;
+    // called to indicate a failure with proxy CONNECT
+    virtual void SetProxyConnectFailed() = 0;
     
     // called to retrieve the request headers of the transaction
     virtual nsHttpRequestHead *RequestHead() = 0;
 
     // determine the number of real http/1.x transactions on this
     // abstract object. Pipelines may have multiple, SPDY has 0,
     // normal http transactions have 1.
     virtual PRUint32 Http1xTransactionCount() = 0;
@@ -144,17 +144,17 @@ public:
                            nsresult status, PRUint64 progress); \
     bool     IsDone(); \
     nsresult Status(); \
     PRUint8  Caps();   \
     PRUint32 Available(); \
     nsresult ReadSegments(nsAHttpSegmentReader *, PRUint32, PRUint32 *); \
     nsresult WriteSegments(nsAHttpSegmentWriter *, PRUint32, PRUint32 *); \
     void     Close(nsresult reason);                                    \
-    void     SetSSLConnectFailed();                                     \
+    void     SetProxyConnectFailed();                                   \
     nsHttpRequestHead *RequestHead();                                   \
     PRUint32 Http1xTransactionCount();                                  \
     nsresult TakeSubTransactions(nsTArray<nsRefPtr<nsAHttpTransaction> > &outTransactions); \
     nsresult AddTransaction(nsAHttpTransaction *);                      \
     PRUint32 PipelineDepth();                                           \
     nsresult SetPipelinePosition(PRInt32);                              \
     PRInt32  PipelinePosition();
 
--- a/netwerk/protocol/http/nsHttpChannel.cpp
+++ b/netwerk/protocol/http/nsHttpChannel.cpp
@@ -704,18 +704,18 @@ nsHttpChannel::SetupTransaction()
             LOG(("  pipelining disallowed\n"));
             mCaps &= ~NS_HTTP_ALLOW_PIPELINING;
         }
     }
 
     if (!mAllowSpdy)
         mCaps |= NS_HTTP_DISALLOW_SPDY;
 
-    // use the URI path if not proxying (transparent proxying such as SSL proxy
-    // does not count here). also, figure out what version we should be speaking.
+    // Use the URI path if not proxying (transparent proxying such as proxy
+    // CONNECT does not count here). Also figure out what HTTP version to use.
     nsCAutoString buf, path;
     nsCString* requestURI;
     if (mConnectionInfo->UsingConnect() ||
         !mConnectionInfo->UsingHttpProxy()) {
         rv = mURI->GetPath(path);
         if (NS_FAILED(rv)) return rv;
         // path may contain UTF-8 characters, so ensure that they're escaped.
         if (NS_EscapeURL(path.get(), path.Length(), esc_OnlyNonASCII, buf))
@@ -981,31 +981,31 @@ nsHttpChannel::CallOnStartRequest()
             CloseOfflineCacheEntry();
         }
     }
 
     return NS_OK;
 }
 
 nsresult
-nsHttpChannel::ProcessFailedSSLConnect(PRUint32 httpStatus)
+nsHttpChannel::ProcessFailedProxyConnect(PRUint32 httpStatus)
 {
-    // Failure to set up SSL proxy tunnel means one of the following:
+    // Failure to set up a proxy tunnel via CONNECT means one of the following:
     // 1) Proxy wants authorization, or forbids.
     // 2) DNS at proxy couldn't resolve target URL.
     // 3) Proxy connection to target failed or timed out.
-    // 4) Eve noticed our proxy CONNECT, and is replying with malicious HTML.
-    // 
-    // Our current architecture will parse response content with the
-    // permission of the target URL!  Given #4, we must avoid rendering the
-    // body of the reply, and instead give the user a (hopefully helpful) 
+    // 4) Eve intercepted our CONNECT, and is replying with malicious HTML.
+    //
+    // Our current architecture would parse the proxy's response content with
+    // the permission of the target URL.  Given #4, we must avoid rendering the
+    // body of the reply, and instead give the user a (hopefully helpful)
     // boilerplate error page, based on just the HTTP status of the reply.
 
     NS_ABORT_IF_FALSE(mConnectionInfo->UsingConnect(),
-                      "SSL connect failed but not using SSL?");
+                      "proxy connect failed but not using CONNECT?");
     nsresult rv;
     switch (httpStatus) 
     {
     case 300: case 301: case 302: case 303: case 307: case 308:
         // Bad redirect: not top-level, or it's a POST, bad/missing Location,
         // or ProcessRedirect() failed for some other reason.  Legal
         // redirects that fail because site not available, etc., are handled
         // elsewhere, in the regular codepath.
@@ -1046,31 +1046,23 @@ nsHttpChannel::ProcessFailedSSLConnect(P
         //              is taking too long to respond."
         rv = NS_ERROR_NET_TIMEOUT;
         break;
     // Confused proxy server or malicious response
     default:
         rv = NS_ERROR_PROXY_CONNECTION_REFUSED; 
         break;
     }
-    LOG(("Cancelling failed SSL proxy connection [this=%p httpStatus=%u]\n",
+    LOG(("Cancelling failed proxy CONNECT [this=%p httpStatus=%u]\n",
          this, httpStatus)); 
     Cancel(rv);
     CallOnStartRequest();
     return rv;
 }
 
-bool
-nsHttpChannel::ShouldSSLProxyResponseContinue(PRUint32 httpStatus)
-{
-    // When SSL connect has failed, allow proxy reply to continue only if it's
-    // a 407 (proxy authentication required) response
-    return (httpStatus == 407);
-}
-
 /**
  * Decide whether or not to remember Strict-Transport-Security, and whether
  * or not to enforce channel integrity.
  *
  * @return NS_ERROR_FAILURE if there's security information missing even though
  *             it's an HTTPS connection.
  */
 nsresult
@@ -1158,20 +1150,21 @@ nsresult
 nsHttpChannel::ProcessResponse()
 {
     nsresult rv;
     PRUint32 httpStatus = mResponseHead->Status();
 
     LOG(("nsHttpChannel::ProcessResponse [this=%p httpStatus=%u]\n",
         this, httpStatus));
 
-    if (mTransaction->SSLConnectFailed()) {
-        if (!ShouldSSLProxyResponseContinue(httpStatus))
-            return ProcessFailedSSLConnect(httpStatus);
-        // If SSL proxy response needs to complete, wait to process connection
+    if (mTransaction->ProxyConnectFailed()) {
+        // Only allow 407 (authentication required) to continue
+        if (httpStatus != 407)
+            return ProcessFailedProxyConnect(httpStatus);
+        // If proxy CONNECT response needs to complete, wait to process connection
         // for Strict-Transport-Security.
     } else {
         // Given a successful connection, process any STS data that's relevant.
         rv = ProcessSTSHeader();
         NS_ASSERTION(NS_SUCCEEDED(rv), "ProcessSTSHeader failed, continuing load.");
     }
 
     MOZ_ASSERT(!mCachedContentIsValid);
@@ -1265,33 +1258,33 @@ nsHttpChannel::ProcessResponse()
         }
         else {
             successfulReval = true;
         }
         break;
     case 401:
     case 407:
         rv = mAuthProvider->ProcessAuthentication(
-            httpStatus, mTransaction->SSLConnectFailed());
+            httpStatus, mTransaction->ProxyConnectFailed());
         if (rv == NS_ERROR_IN_PROGRESS)  {
             // authentication prompt has been invoked and result
             // is expected asynchronously
             mAuthRetryPending = true;
             // suspend the transaction pump to stop receiving the
             // unauthenticated content data. We will throw that data
             // away when user provides credentials or resume the pump
             // when user refuses to authenticate.
             LOG(("Suspending the transaction, asynchronously prompting for credentials"));
             mTransactionPump->Suspend();
             rv = NS_OK;
         }
         else if (NS_FAILED(rv)) {
             LOG(("ProcessAuthentication failed [rv=%x]\n", rv));
-            if (mTransaction->SSLConnectFailed())
-                return ProcessFailedSSLConnect(httpStatus);
+           if (mTransaction->ProxyConnectFailed())
+               return ProcessFailedProxyConnect(httpStatus);
             if (!mAuthRetryPending)
                 mAuthProvider->CheckForSuperfluousAuth();
             rv = ProcessNormal();
         }
         else
             mAuthRetryPending = true; // see DoAuthRetry
         break;
     default:
@@ -1352,18 +1345,18 @@ nsHttpChannel::ContinueProcessResponse(n
             // Store response in the offline cache
             InitOfflineCacheEntry();
             CloseOfflineCacheEntry();
         }
         return NS_OK;
     }
 
     LOG(("ContinueProcessResponse got failure result [rv=%x]\n", rv));
-    if (mTransaction->SSLConnectFailed()) {
-        return ProcessFailedSSLConnect(mRedirectType);
+    if (mTransaction->ProxyConnectFailed()) {
+        return ProcessFailedProxyConnect(mRedirectType);
     }
     return ProcessNormal();
 }
 
 nsresult
 nsHttpChannel::ProcessNormal()
 {
     nsresult rv;
--- a/netwerk/protocol/http/nsHttpChannel.h
+++ b/netwerk/protocol/http/nsHttpChannel.h
@@ -167,18 +167,17 @@ private:
     nsresult ProcessResponse();
     nsresult ContinueProcessResponse(nsresult);
     nsresult ProcessNormal();
     nsresult ContinueProcessNormal(nsresult);
     nsresult ProcessNotModified();
     nsresult AsyncProcessRedirection(PRUint32 httpStatus);
     nsresult ContinueProcessRedirection(nsresult);
     nsresult ContinueProcessRedirectionAfterFallback(nsresult);
-    bool     ShouldSSLProxyResponseContinue(PRUint32 httpStatus);
-    nsresult ProcessFailedSSLConnect(PRUint32 httpStatus);
+    nsresult ProcessFailedProxyConnect(PRUint32 httpStatus);
     nsresult ProcessFallback(bool *waitingForRedirectCallback);
     nsresult ContinueProcessFallback(nsresult);
     void     HandleAsyncAbort();
     nsresult EnsureAssocReq();
 
     nsresult ContinueOnStartRequest1(nsresult);
     nsresult ContinueOnStartRequest2(nsresult);
     nsresult ContinueOnStartRequest3(nsresult);
--- a/netwerk/protocol/http/nsHttpConnection.cpp
+++ b/netwerk/protocol/http/nsHttpConnection.cpp
@@ -823,19 +823,19 @@ nsHttpConnection::OnHeadersAvailable(nsA
     }
 
     if (!foundKeepAliveMax && mRemainingConnectionUses && !mUsingSpdyVersion)
         --mRemainingConnectionUses;
 
     if (!mProxyConnectStream)
         HandleAlternateProtocol(responseHead);
 
-    // if we're doing an SSL proxy connect, then we need to check whether or not
-    // the connect was successful.  if so, then we have to reset the transaction
-    // and step-up the socket connection to SSL. finally, we have to wake up the
+    // If we're doing a proxy connect, we need to check whether or not
+    // it was successful.  If so, we have to reset the transaction and step-up
+    // the socket connection if using SSL. Finally, we have to wake up the
     // socket write request.
     if (mProxyConnectStream) {
         NS_ABORT_IF_FALSE(!mUsingSpdyVersion,
                           "SPDY NPN Complete while using proxy connect stream");
         mProxyConnectStream = 0;
         if (responseHead->Status() == 200) {
             LOG(("proxy CONNECT succeeded! ssl=%s\n",
                  mConnInfo->UsingSSL() ? "true" :"false"));
@@ -850,17 +850,17 @@ nsHttpConnection::OnHeadersAvailable(nsA
             mProxyConnectInProgress = false;
             rv = mSocketOut->AsyncWait(this, 0, 0, nsnull);
             // XXX what if this fails -- need to handle this error
             NS_ASSERTION(NS_SUCCEEDED(rv), "mSocketOut->AsyncWait failed");
         }
         else {
             LOG(("proxy CONNECT failed! ssl=%s\n",
                  mConnInfo->UsingSSL() ? "true" :"false"));
-            mTransaction->SetSSLConnectFailed();
+            mTransaction->SetProxyConnectFailed();
         }
     }
     
     const char *upgradeReq = requestHead->PeekHeader(nsHttp::Upgrade);
     if (upgradeReq) {
         LOG(("HTTP Upgrade in play - disable keepalive\n"));
         DontReuse();
     }
@@ -1190,18 +1190,18 @@ nsHttpConnection::OnSocketWritable()
 
     nsresult rv;
     PRUint32 n;
     bool again = true;
 
     do {
         mSocketOutCondition = NS_OK;
 
-        // if we're doing an SSL proxy connect, then we need to bypass calling
-        // into the transaction.
+        // If we're doing a proxy connect, then we need to bypass calling into
+        // the transaction.
         //
         // NOTE: this code path can't be shared since the transaction doesn't
         // implement nsIInputStream.  doing so is not worth the added cost of
         // extra indirections during normal reading.
         //
         if (mProxyConnectStream) {
             LOG(("  writing CONNECT request stream\n"));
             rv = mProxyConnectStream->ReadSegments(ReadFromStream, this,
--- a/netwerk/protocol/http/nsHttpPipeline.cpp
+++ b/netwerk/protocol/http/nsHttpPipeline.cpp
@@ -340,22 +340,22 @@ nsHttpPipeline::Classification()
         return mConnection->Classification();
 
     LOG(("nsHttpPipeline::Classification this=%p "
          "has null mConnection using CLASS_SOLO default", this));
     return nsAHttpTransaction::CLASS_SOLO;
 }
 
 void
-nsHttpPipeline::SetSSLConnectFailed()
+nsHttpPipeline::SetProxyConnectFailed()
 {
     nsAHttpTransaction *trans = Request(0);
 
     if (trans)
-        trans->SetSSLConnectFailed();
+        trans->SetProxyConnectFailed();
 }
 
 nsHttpRequestHead *
 nsHttpPipeline::RequestHead()
 {
     nsAHttpTransaction *trans = Request(0);
 
     if (trans)
@@ -642,17 +642,17 @@ nsHttpPipeline::WriteSegments(nsAHttpSeg
         return NS_SUCCEEDED(mStatus) ? NS_BASE_STREAM_CLOSED : mStatus;
 
     nsAHttpTransaction *trans; 
     nsresult rv;
 
     trans = Response(0);
     // This code deals with the establishment of a CONNECT tunnel through
     // an HTTP proxy. It allows the connection to do the CONNECT/200
-    // HTTP transaction to establish an SSL tunnel as a precursor to the
+    // HTTP transaction to establish a tunnel as a precursor to the
     // actual pipeline of regular HTTP transactions.
     if (!trans && mRequestQ.Length() &&
         mConnection->IsProxyConnectInProgress()) {
         LOG(("nsHttpPipeline::WriteSegments [this=%p] Forced Delegation\n",
              this));
         trans = Request(0);
     }
 
--- a/netwerk/protocol/http/nsHttpTransaction.cpp
+++ b/netwerk/protocol/http/nsHttpTransaction.cpp
@@ -96,17 +96,17 @@ nsHttpTransaction::nsHttpTransaction()
     , mTransactionDone(false)
     , mResponseIsComplete(false)
     , mDidContentStart(false)
     , mNoContent(false)
     , mSentData(false)
     , mReceivedData(false)
     , mStatusEventPending(false)
     , mHasRequestBody(false)
-    , mSSLConnectFailed(false)
+    , mProxyConnectFailed(false)
     , mHttpResponseMatched(false)
     , mPreserveStream(false)
     , mReportedStart(false)
     , mReportedResponseHeader(false)
     , mForTakeResponseHead(nsnull)
     , mResponseHeadTaken(false)
 {
     LOG(("Creating nsHttpTransaction @%x\n", this));
@@ -347,19 +347,19 @@ nsHttpTransaction::TakeResponseHead()
     }
 
     head = mResponseHead;
     mResponseHead = nsnull;
     return head;
 }
 
 void
-nsHttpTransaction::SetSSLConnectFailed()
+nsHttpTransaction::SetProxyConnectFailed()
 {
-    mSSLConnectFailed = true;
+    mProxyConnectFailed = true;
 }
 
 nsHttpRequestHead *
 nsHttpTransaction::RequestHead()
 {
     return mRequestHead;
 }
 
--- a/netwerk/protocol/http/nsHttpTransaction.h
+++ b/netwerk/protocol/http/nsHttpTransaction.h
@@ -89,17 +89,17 @@ public:
 
     // Called to take ownership of the response headers; the transaction
     // will drop any reference to the response headers after this call.
     nsHttpResponseHead *TakeResponseHead();
 
     // Called to find out if the transaction generated a complete response.
     bool ResponseIsComplete() { return mResponseIsComplete; }
 
-    bool      SSLConnectFailed() { return mSSLConnectFailed; }
+    bool      ProxyConnectFailed() { return mProxyConnectFailed; }
 
     // SetPriority() may only be used by the connection manager.
     void    SetPriority(PRInt32 priority) { mPriority = priority; }
     PRInt32    Priority()                 { return mPriority; }
 
     const TimingStruct& Timings() const { return mTimings; }
     enum Classifier Classification() { return mClassification; }
 
@@ -184,17 +184,17 @@ private:
     bool                            mTransactionDone;
     bool                            mResponseIsComplete;
     bool                            mDidContentStart;
     bool                            mNoContent; // expecting an empty entity body
     bool                            mSentData;
     bool                            mReceivedData;
     bool                            mStatusEventPending;
     bool                            mHasRequestBody;
-    bool                            mSSLConnectFailed;
+    bool                            mProxyConnectFailed;
     bool                            mHttpResponseMatched;
     bool                            mPreserveStream;
 
     // mClosed           := transaction has been explicitly closed
     // mTransactionDone  := transaction ran to completion or was interrupted
     // mResponseComplete := transaction ran to completion
 
     // For Restart-In-Progress Functionality
--- a/netwerk/protocol/http/nsIHttpAuthManager.idl
+++ b/netwerk/protocol/http/nsIHttpAuthManager.idl
@@ -22,17 +22,17 @@
 [scriptable, uuid(7ce8e9d1-8b4b-4883-a307-66fe12a50153)]
 interface nsIHttpAuthManager : nsISupports
 {
     /**
      * Lookup auth identity.
      *
      * @param aScheme
      *        the URL scheme (e.g., "http").  NOTE: for proxy authentication,
-     *        this should be "http" (this includes authentication for SSL
+     *        this should be "http" (this includes authentication for CONNECT
      *        tunneling).
      * @param aHost
      *        the host of the server issuing a challenge (ASCII only).
      * @param aPort
      *        the port of the server issuing a challenge.
      * @param aAuthType
      *        optional string identifying auth type used (e.g., "basic")
      * @param aRealm
@@ -56,17 +56,17 @@ interface nsIHttpAuthManager : nsISuppor
                          out AString aUserName,
                          out AString aUserPassword);
 
     /**
      * Store auth identity.
      *
      * @param aScheme
      *        the URL scheme (e.g., "http").  NOTE: for proxy authentication,
-     *        this should be "http" (this includes authentication for SSL
+     *        this should be "http" (this includes authentication for CONNECT
      *        tunneling).
      * @param aHost
      *        the host of the server issuing a challenge (ASCII only).
      * @param aPort
      *        the port of the server issuing a challenge.
      * @param aAuthType
      *        optional string identifying auth type used (e.g., "basic")
      * @param aRealm