opentxs::OTEnvelope Class Reference

#include <OTEnvelope.hpp>

Public Member Functions
EXPORT	OTEnvelope ()
EXPORT	OTEnvelope (const OTASCIIArmor &theArmoredText)
EXPORT	OTEnvelope (const OTString &strArmorWithBookends)
virtual EXPORT	~OTEnvelope ()
EXPORT bool	Encrypt (const OTString &theInput, OTSymmetricKey &theKey, const OTPassword &thePassword)
EXPORT bool	Decrypt (OTString &theOutput, const OTSymmetricKey &theKey, const OTPassword &thePassword)
EXPORT bool	Seal (const OTPseudonym &theRecipient, const OTString &theInput)
EXPORT bool	Seal (const OTAsymmetricKey &RecipPubKey, const OTString &theInput)
EXPORT bool	Seal (setOfNyms &theRecipients, const OTString &theInput)
EXPORT bool	Seal (mapOfAsymmetricKeys &RecipPubKeys, const OTString &theInput)
EXPORT bool	Open (const OTPseudonym &theRecipient, OTString &theOutput, const OTPasswordData *pPWData=nullptr)
EXPORT bool	GetAsciiArmoredData (OTASCIIArmor &theArmoredText, bool bLineBreaks=true) const
EXPORT bool	GetAsBookendedString (OTString &strArmorWithBookends, bool bEscaped=false) const
EXPORT bool	SetAsciiArmoredData (const OTASCIIArmor &theArmoredText, bool bLineBreaks=true)
EXPORT bool	SetFromBookendedString (const OTString &strArmorWithBookends, bool bEscaped=false)

Friends
class	OTPayload

Detailed Description

Definition at line 156 of file OTEnvelope.hpp.

Constructor & Destructor Documentation

opentxs::OTEnvelope::OTEnvelope

(

)

Definition at line 630 of file OTEnvelope.cpp.

{
}

opentxs::OTEnvelope::OTEnvelope

(

const OTASCIIArmor &

theArmoredText

)

Definition at line 625 of file OTEnvelope.cpp.

{
    SetAsciiArmoredData(theArmoredText);
}

EXPORT opentxs::OTEnvelope::OTEnvelope

(

const OTString &

strArmorWithBookends

)

opentxs::OTEnvelope::~OTEnvelope ( )

virtual

Definition at line 634 of file OTEnvelope.cpp.

{
}

Member Function Documentation

bool opentxs::OTEnvelope::Decrypt	(	OTString &	theOutput,
		const OTSymmetricKey &	theKey,
		const OTPassword &	thePassword
	)

Definition at line 364 of file OTEnvelope.cpp.

{
    const char* szFunc = "OTEnvelope::Decrypt";

    OT_ASSERT(
        (thePassword.isPassword() && (thePassword.getPasswordSize() > 0)) ||
        (thePassword.isMemory() && (thePassword.getMemorySize() > 0)));
    OT_ASSERT(theKey.IsGenerated());

    OTPassword theRawSymmetricKey;

    if (false ==
        theKey.GetRawKeyFromPassphrase(thePassword, theRawSymmetricKey)) {
        otErr << szFunc << ": Failed trying to retrieve raw symmetric key "
                           "using password. (Wrong password?)\n";
        return false;
    }

    uint32_t nRead = 0;
    uint32_t nRunningTotal = 0;

    m_dataContents.reset(); // Reset the fread position on this object to 0.

    //
    // Read the ENVELOPE TYPE (as network order version -- and convert to host
    // version.)
    //
    // 0 == Error
    // 1 == Asymmetric Key  (this function -- Seal / Open)
    // 2 == Symmetric Key   (other functions -- Encrypt / Decrypt use this.)
    // Anything else: error.
    //
    uint16_t env_type_n = 0;

    if (0 == (nRead = m_dataContents.OTfread(
                  reinterpret_cast<uint8_t*>(&env_type_n),
                  static_cast<uint32_t>(sizeof(env_type_n))))) {
        otErr << szFunc << ": Error reading Envelope Type. Expected "
                           "asymmetric(1) or symmetric (2).\n";
        return false;
    }
    nRunningTotal += nRead;
    OT_ASSERT(nRead == static_cast<uint32_t>(sizeof(env_type_n)));

    // convert that envelope type from network to HOST endian.
    //
    const uint16_t env_type =
        static_cast<uint16_t>(ntohs(static_cast<uint16_t>(env_type_n)));
    //  nRunningTotal += env_type;    // NOPE! Just because envelope type is 1
    // or 2, doesn't mean we add 1 or 2 extra bytes to the length here. Nope!

    if (2 != env_type) {
        const uint32_t l_env_type = static_cast<uint32_t>(env_type);
        otErr << szFunc << ": Error: Expected Envelope for Symmetric key (type "
                           "2) but instead found type: " << l_env_type << ".\n";
        return false;
    }

    // Read network-order IV size (and convert to host version)
    //
    const uint32_t max_iv_length =
        OTCryptoConfig::SymmetricIvSize(); // I believe this is a max length, so
                                           // it may not match the actual length
                                           // of the IV.

    // Read the IV SIZE (network order version -- convert to host version.)
    //
    uint32_t iv_size_n = 0;

    if (0 == (nRead = m_dataContents.OTfread(
                  reinterpret_cast<uint8_t*>(&iv_size_n),
                  static_cast<uint32_t>(sizeof(iv_size_n))))) {
        otErr << szFunc << ": Error reading IV Size.\n";
        return false;
    }
    nRunningTotal += nRead;
    OT_ASSERT(nRead == static_cast<uint32_t>(sizeof(iv_size_n)));

    // convert that iv size from network to HOST endian.
    //
    const uint32_t iv_size_host_order = ntohl(iv_size_n);

    if (iv_size_host_order > max_iv_length) {
        otErr << szFunc << ": Error: iv_size ("
              << static_cast<int64_t>(iv_size_host_order)
              << ") is larger than max_iv_length ("
              << static_cast<int64_t>(max_iv_length) << ").\n";
        return false;
    }
    //  nRunningTotal += iv_size_host_order; // Nope!

    // Then read the IV (initialization vector) itself.
    //
    OTPayload theIV;
    theIV.SetPayloadSize(iv_size_host_order);

    if (0 == (nRead = m_dataContents.OTfread(
                  static_cast<uint8_t*>(
                      const_cast<void*>(theIV.GetPayloadPointer())),
                  static_cast<uint32_t>(iv_size_host_order)))) {
        otErr << szFunc << ": Error reading initialization vector.\n";
        return false;
    }
    nRunningTotal += nRead;
    OT_ASSERT(nRead == static_cast<uint32_t>(iv_size_host_order));

    OT_ASSERT(nRead <= max_iv_length);

    // We create an OTPayload object to store the ciphertext itself, which
    // begins AFTER the end of the IV.
    // So we see pointer + nRunningTotal as the starting point for the
    // ciphertext.
    // the size of the ciphertext, meanwhile, is the size of the entire thing,
    // MINUS nRunningTotal.
    //
    OTPayload theCipherText(
        static_cast<const void*>(
            static_cast<const uint8_t*>(m_dataContents.GetPointer()) +
            nRunningTotal),
        m_dataContents.GetSize() - nRunningTotal);

    // Now we've got all the pieces together, let's try to decrypt it...
    //
    OTPayload thePlaintext; // for output.

    const bool bDecrypted = OTCrypto::It()->Decrypt(
        theRawSymmetricKey, // The symmetric key, in clear form.
        static_cast<const char*>(
            theCipherText.GetPayloadPointer()), // This is the Ciphertext.
        theCipherText.GetSize(),
        theIV, thePlaintext); // OUTPUT. (Recovered plaintext.) You can pass
                              // OTPassword& OR OTPayload& here (either will
                              // work.)

    // theOutput is where we'll put the decrypted data.
    //
    theOutput.Release();

    if (bDecrypted) {

        // Make sure it's null-terminated...
        //
        uint32_t nIndex = thePlaintext.GetSize() - 1;
        (static_cast<uint8_t*>(
            const_cast<void*>(thePlaintext.GetPointer())))[nIndex] = '\0';

        // Set it into theOutput (to return the plaintext to the caller)
        //
        theOutput.Set(static_cast<const char*>(thePlaintext.GetPointer()));
    }

    return bDecrypted;
}

bool opentxs::OTEnvelope::Encrypt	(	const OTString &	theInput,
		OTSymmetricKey &	theKey,
		const OTPassword &	thePassword
	)

Definition at line 245 of file OTEnvelope.cpp.

{
    OT_ASSERT(
        (thePassword.isPassword() && (thePassword.getPasswordSize() > 0)) ||
        (thePassword.isMemory() && (thePassword.getMemorySize() > 0)));
    OT_ASSERT(theInput.Exists());

    // Generate a random initialization vector.
    //
    OTPayload theIV;

    if (!theIV.Randomize(OTCryptoConfig::SymmetricIvSize())) {
        otErr << __FUNCTION__ << ": Failed trying to randomly generate IV.\n";
        return false;
    }

    // If the symmetric key hasn't already been generated, we'll just do that
    // now...
    // (The passphrase is used to derive another key that is used to encrypt the
    // actual symmetric key, and to access it later.)
    //
    if ((false == theKey.IsGenerated()) &&
        (false == theKey.GenerateKey(thePassword))) {
        otErr << __FUNCTION__
              << ": Failed trying to generate symmetric key using password.\n";
        return false;
    }

    if (!theKey.HasHashCheck()) {
        if (!theKey.GenerateHashCheck(thePassword)) {
            otErr << __FUNCTION__
                  << ": Failed trying to generate hash check using password.\n";
            return false;
        }
    }

    OT_ASSERT(theKey.HasHashCheck());

    OTPassword theRawSymmetricKey;

    if (false ==
        theKey.GetRawKeyFromPassphrase(thePassword, theRawSymmetricKey)) {
        otErr << __FUNCTION__ << ": Failed trying to retrieve raw symmetric "
                                 "key using password.\n";
        return false;
    }

    OTPayload theCipherText;

    const bool bEncrypted = OTCrypto::It()->Encrypt(
        theRawSymmetricKey,       // The symmetric key, in clear form.
        theInput.Get(),           // This is the Plaintext.
        theInput.GetLength() + 1, // for null terminator
        theIV,                    // Initialization vector.
        theCipherText);           // OUTPUT. (Ciphertext.)

    //
    // Success?
    //
    if (!bEncrypted) {
        otErr << __FUNCTION__ << ": (static) call failed to encrypt. Wrong "
                                 "key? (Returning false.)\n";
        return false;
    }

    // This is where the envelope final contents will be placed,
    // including the envelope type, the size of the IV, the IV
    // itself, and the ciphertext.
    //
    m_dataContents.Release();

    // Write the ENVELOPE TYPE (network order version.)
    //
    // 0 == Error
    // 1 == Asymmetric Key  (other functions -- Seal / Open.)
    // 2 == Symmetric Key   (this function -- Encrypt / Decrypt.)
    // Anything else: error.

    uint16_t env_type_n = static_cast<uint16_t>(htons(static_cast<uint16_t>(
        2))); // Calculate "network-order" version of envelope type 2.

    m_dataContents.Concatenate(reinterpret_cast<void*>(&env_type_n),
                               // (uint32_t here is the 2nd parameter to
                               // Concatenate, and has nothing to do with
                               // env_type_n being uint16_t)
                               static_cast<uint32_t>(sizeof(env_type_n)));

    // Write IV size (in network-order)
    //
    uint32_t ivlen =
        OTCryptoConfig::SymmetricIvSize(); // Length of IV for this cipher...
    OT_ASSERT(ivlen >= theIV.GetSize());
    uint32_t ivlen_n = htonl(
        theIV.GetSize()); // Calculate "network-order" version of iv length.

    m_dataContents.Concatenate(reinterpret_cast<void*>(&ivlen_n),
                               static_cast<uint32_t>(sizeof(ivlen_n)));

    // Write the IV itself.
    //
    m_dataContents.Concatenate(theIV.GetPayloadPointer(),
                               static_cast<uint32_t>(theIV.GetSize()));

    // Write the Ciphertext.
    //
    m_dataContents.Concatenate(theCipherText.GetPayloadPointer(),
                               static_cast<uint32_t>(theCipherText.GetSize()));

    // We don't write the size of the ciphertext before the ciphertext itself,
    // since the decryption is able to deduce the size based on the total
    // envelope
    // size minus the other pieces. We might still want to add that size here,
    // however.
    // (for security / safety reasons.)

    return true;
}

bool opentxs::OTEnvelope::GetAsBookendedString	(	OTString &	strArmorWithBookends,
		bool	bEscaped = false
	)		const

Definition at line 184 of file OTEnvelope.cpp.

{
    OTASCIIArmor theArmoredText;
    // This function will base64 ENCODE m_dataContents, and then
    // Set() that as the string contents on theArmoredText.
    const bool bSetData = theArmoredText.SetData(
        m_dataContents, true); // bLineBreaks=true (by default anyway.)

    if (bSetData) {
        const bool bWritten = theArmoredText.WriteArmoredString(
            strArmorWithBookends, "ENVELOPE", // todo hardcoded
            bEscaped);
        if (!bWritten)
            otErr << __FUNCTION__ << ": Failed while calling: "
                                     "theArmoredText.WriteArmoredString\n";
        else
            return true;
    }
    else
        otErr << __FUNCTION__
              << ": Failed while calling: "
                 "theArmoredText.SetData(m_dataContents, true)\n";

    return false;
}

bool opentxs::OTEnvelope::GetAsciiArmoredData	(	OTASCIIArmor &	theArmoredText,
		bool	bLineBreaks = true
	)		const

Definition at line 162 of file OTEnvelope.cpp.

{
    return theArmoredText.SetData(m_dataContents, bLineBreaks);
}

bool opentxs::OTEnvelope::Open	(	const OTPseudonym &	theRecipient,
		OTString &	theOutput,
		const OTPasswordData *	pPWData = nullptr
	)

Definition at line 581 of file OTEnvelope.cpp.

{
    return OTCrypto::It()->Open(m_dataContents, theRecipient, theOutput,
                                pPWData);
}

bool opentxs::OTEnvelope::Seal	(	const OTPseudonym &	theRecipient,
		const OTString &	theInput
	)

Definition at line 521 of file OTEnvelope.cpp.

{
    OTString strNymID;
    mapOfAsymmetricKeys theKeys;
    theRecipient.GetIdentifier(strNymID);
    theKeys.insert(std::pair<std::string, OTAsymmetricKey*>(
        strNymID.Get(),
        const_cast<OTAsymmetricKey*>(&(theRecipient.GetPublicEncrKey()))));

    return Seal(theKeys, theInput);
}

bool opentxs::OTEnvelope::Seal	(	const OTAsymmetricKey &	RecipPubKey,
		const OTString &	theInput
	)

Definition at line 556 of file OTEnvelope.cpp.

{
    mapOfAsymmetricKeys theKeys;
    theKeys.insert(std::pair<std::string, OTAsymmetricKey*>(
        "", // Normally the NymID goes here, but we don't know what it is, in
            // this case.
        const_cast<OTAsymmetricKey*>(&RecipPubKey)));

    return Seal(theKeys, theInput);
}

bool opentxs::OTEnvelope::Seal	(	setOfNyms &	theRecipients,
		const OTString &	theInput
	)

Definition at line 533 of file OTEnvelope.cpp.

{
    mapOfAsymmetricKeys RecipPubKeys;

    // Loop through theRecipients, and add the public key of each one to a set
    // of keys.
    for (auto& it : theRecipients) {
        OTPseudonym* pNym = it;
        OT_ASSERT_MSG(nullptr != pNym,
                      "OTEnvelope::Seal: Assert: nullptr pseudonym pointer.");

        OTString strNymID;
        pNym->GetIdentifier(strNymID);
        RecipPubKeys.insert(std::pair<std::string, OTAsymmetricKey*>(
            strNymID.Get(),
            const_cast<OTAsymmetricKey*>(&(pNym->GetPublicEncrKey()))));
    }

    if (RecipPubKeys.empty()) return false;

    return Seal(RecipPubKeys, theInput);
}

bool opentxs::OTEnvelope::Seal	(	mapOfAsymmetricKeys &	RecipPubKeys,
		const OTString &	theInput
	)

Definition at line 570 of file OTEnvelope.cpp.

{
    OT_ASSERT_MSG(!RecipPubKeys.empty(),
                  "OTEnvelope::Seal: ASSERT: RecipPubKeys.size() > 0");

    return OTCrypto::It()->Seal(RecipPubKeys, theInput, m_dataContents);
}

bool opentxs::OTEnvelope::SetAsciiArmoredData	(	const OTASCIIArmor &	theArmoredText,
		bool	bLineBreaks = true
	)

Definition at line 178 of file OTEnvelope.cpp.

{
    return theArmoredText.GetData(m_dataContents, bLineBreaks);
}

bool opentxs::OTEnvelope::SetFromBookendedString	(	const OTString &	strArmorWithBookends,
		bool	bEscaped = false
	)

Definition at line 212 of file OTEnvelope.cpp.

{
    OTASCIIArmor theArmoredText;
    const bool bLoaded = theArmoredText.LoadFromString(
        const_cast<OTString&>(strArmorWithBookends),
        bEscaped); // std::string str_override="-----BEGIN");

    if (bLoaded) {
        // This function will base64 DECODE theArmoredText's string contents
        // and return them as binary in m_dataContents
        const bool bGotData =
            theArmoredText.GetData(m_dataContents, true); // bLineBreaks = true

        if (!bGotData)
            otErr << __FUNCTION__ << ": Failed while calling: "
                                     "theArmoredText.GetData\n";
        else
            return true;
    }
    else
        otErr << __FUNCTION__ << ": Failed while calling: "
                                 "theArmoredText.LoadFromString\n";

    return false;
}

Friends And Related Function Documentation

friend class OTPayload

friend

Definition at line 158 of file OTEnvelope.hpp.

---

The documentation for this class was generated from the following files:

• /usr/local/src/opentxs/include/opentxs/core/crypto/OTEnvelope.hpp
• /usr/local/src/opentxs/src/core/crypto/OTEnvelope.cpp