Add a warning about Decrypt() being used as a padding oracle.

crypto/encryptor.h

 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef CRYPTO_ENCRYPTOR_H_
 #define CRYPTO_ENCRYPTOR_H_
 #pragma once
 
 #include <string>
 
@@ skipping 52 matching lines @@
   //
   // If |mode| is CBC, |iv| must not be empty; if it is CTR, then |iv| must be
   // empty.
   bool Init(SymmetricKey* key, Mode mode, const base::StringPiece& iv);
 
   // Encrypts |plaintext| into |ciphertext|.  |plaintext| may only be empty if
   // the mode is CBC.
   bool Encrypt(const base::StringPiece& plaintext, std::string* ciphertext);
 
   // Decrypts |ciphertext| into |plaintext|.  |ciphertext| must not be empty.
+  //
+  // WARNING: In CBC mode, Decrypt() returns false if it detects the padding
+  // in the decrypted plaintext is wrong. Padding errors can result from
+  // tampered ciphertext or a wrong decryption key. But successful decryption
+  // does not imply the authenticity of the data. The caller of Decrypt()
+  // must either authenticate the ciphertext before decrypting it, or take
+  // care to not report decryption failure. Otherwise it could inadvertently
+  // be used as a padding oracle.

[agl, 2012/04/24 22:27:48]

...a padding oracle to attack the cryptosystem.

(I might be unclear, to a non-crypto person, that a padding oracle is bad.)

   bool Decrypt(const base::StringPiece& ciphertext, std::string* plaintext);
 
   // Sets the counter value when in CTR mode. Currently only 128-bits
   // counter value is supported.
   //
   // Returns true only if update was successful.
   bool SetCounter(const base::StringPiece& counter);
 
   // TODO(albertb): Support streaming encryption.
 
@@ skipping 47 matching lines @@
   std::string iv_;
 #elif defined(OS_WIN)
   ScopedHCRYPTKEY capi_key_;
   DWORD block_size_;
 #endif
 };
 
 }  // namespace crypto
 
 #endif  // CRYPTO_ENCRYPTOR_H_