ContentElement.java

/**
 *
 * Copyright 2020 Paul Schaub
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.jivesoftware.smackx.stanza_content_encryption.element;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.Date;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

import javax.xml.namespace.QName;

import org.jivesoftware.smack.packet.ExtensionElement;
import org.jivesoftware.smack.packet.XmlElement;
import org.jivesoftware.smack.packet.XmlEnvironment;
import org.jivesoftware.smack.util.Objects;
import org.jivesoftware.smack.util.XmlStringBuilder;

import org.jivesoftware.smackx.address.packet.MultipleAddresses;
import org.jivesoftware.smackx.hints.element.MessageProcessingHint;
import org.jivesoftware.smackx.sid.element.StanzaIdElement;

import org.jxmpp.jid.Jid;

/**
 * Extension element that holds the payload element, as well as a list of affix elements.
 * In SCE, the XML representation of this element is what will be encrypted using the encryption mechanism of choice.
 */
public class ContentElement implements ExtensionElement {

    private static final String NAMESPACE_UNVERSIONED = "urn:xmpp:sce";
    public static final String NAMESPACE_0 = NAMESPACE_UNVERSIONED + ":0";
    public static final String NAMESPACE = NAMESPACE_0;
    public static final String ELEMENT = "content";
    public static final QName QNAME = new QName(NAMESPACE, ELEMENT);

    private final PayloadElement payload;
    private final List<AffixElement> affixElements;

    ContentElement(PayloadElement payload, List<AffixElement> affixElements) {
        this.payload = payload;
        this.affixElements = Collections.unmodifiableList(affixElements);
    }

    /**
     * Return the {@link PayloadElement} which holds the sensitive payload extensions.
     *
     * @return payload element
     */
    public PayloadElement getPayload() {
        return payload;
    }

    /**
     * Return a list of affix elements.
     * Those are elements that need to be verified upon reception by the encryption mechanisms implementation.
     *
     * @see <a href="https://xmpp.org/extensions/xep-0420.html#affix_elements">
     *     XEP-0420: Stanza Content Encryption - §4. Affix Elements</a>
     *
     * @return list of affix elements
     */
    public List<AffixElement> getAffixElements() {
        return affixElements;
    }

    @Override
    public String getNamespace() {
        return NAMESPACE;
    }

    @Override
    public String getElementName() {
        return ELEMENT;
    }

    @Override
    public XmlStringBuilder toXML(XmlEnvironment xmlEnvironment) {
        XmlStringBuilder xml = new XmlStringBuilder(this).rightAngleBracket();
        xml.append(affixElements);
        xml.append(payload);
        return xml.closeElement(this);
    }

    @Override
    public QName getQName() {
        return QNAME;
    }

    /**
     * Return a {@link Builder} that can be used to build the {@link ContentElement}.
     * @return builder
     */
    public static Builder builder() {
        return new Builder();
    }

    public static final class Builder {
        private static final Set<String> BLACKLISTED_NAMESPACES = Collections.singleton(MessageProcessingHint.NAMESPACE);
        private static final Set<QName> BLACKLISTED_QNAMES = Collections.unmodifiableSet(new HashSet<>(Arrays.asList(
                StanzaIdElement.QNAME,
                MultipleAddresses.QNAME
        )));

        private FromAffixElement from = null;
        private TimestampAffixElement timestamp = null;
        private RandomPaddingAffixElement rpad = null;

        private final List<AffixElement> otherAffixElements = new ArrayList<>();
        private final List<XmlElement> payloadItems = new ArrayList<>();

        private Builder() {

        }

        /**
         * Add an affix element of type 'to' which addresses one recipient.
         * The jid in the 'to' element SHOULD be a bare jid.
         *
         * @param jid jid
         * @return builder
         */
        public Builder addTo(Jid jid) {
            return addTo(new ToAffixElement(jid));
        }

        /**
         * Add an affix element of type 'to' which addresses one recipient.
         *
         * @param to affix element
         * @return builder
         */
        public Builder addTo(ToAffixElement to) {
            this.otherAffixElements.add(Objects.requireNonNull(to, "'to' affix element MUST NOT be null."));
            return this;
        }

        /**
         * Set the senders jid as a 'from' affix element.
         *
         * @param jid jid of the sender
         * @return builder
         */
        public Builder setFrom(Jid jid) {
            return setFrom(new FromAffixElement(jid));
        }

        /**
         * Set the senders jid as a 'from' affix element.
         *
         * @param from affix element
         * @return builder
         */
        public Builder setFrom(FromAffixElement from) {
            this.from = Objects.requireNonNull(from, "'form' affix element MUST NOT be null.");
            return this;
        }

        /**
         * Set the given date as a 'time' affix element.
         *
         * @param date timestamp as date
         * @return builder
         */
        public Builder setTimestamp(Date date) {
            return setTimestamp(new TimestampAffixElement(date));
        }

        /**
         * Set the timestamp of the message as a 'time' affix element.
         *
         * @param timestamp timestamp affix element
         * @return builder
         */
        public Builder setTimestamp(TimestampAffixElement timestamp) {
            this.timestamp = Objects.requireNonNull(timestamp, "'time' affix element MUST NOT be null.");
            return this;
        }

        /**
         * Set some random length random content padding.
         *
         * @return builder
         */
        public Builder setRandomPadding() {
            this.rpad = new RandomPaddingAffixElement();
            return this;
        }

        /**
         * Set the given string as padding.
         * The padding should be of length between 1 and 200 characters.
         *
         * @param padding padding string
         * @return builder
         */
        public Builder setRandomPadding(String padding) {
            return setRandomPadding(new RandomPaddingAffixElement(padding));
        }

        /**
         * Set a padding affix element.
         *
         * @param padding affix element
         * @return builder
         */
        public Builder setRandomPadding(RandomPaddingAffixElement padding) {
            this.rpad = Objects.requireNonNull(padding, "'rpad' affix element MUST NOT be empty.");
            return this;
        }

        /**
         * Add an additional, SCE profile specific affix element.
         *
         * @param customAffixElement additional affix element
         * @return builder
         */
        public Builder addFurtherAffixElement(AffixElement customAffixElement) {
            this.otherAffixElements.add(Objects.requireNonNull(customAffixElement,
                    "Custom affix element MUST NOT be null."));
            return this;
        }

        /**
         * Add a payload item as child element of the payload element.
         * There are some items that are not allowed as payload.
         * Adding those will throw an exception.
         *
         * @see <a href="https://xmpp.org/extensions/xep-0420.html#server-processed">
         *     XEP-0420: Stanza Content Encryption - §9. Server-processed Elements</a>
         *
         * @param payloadItem extension element
         * @return builder
         * @throws IllegalArgumentException in case an extension element from the blacklist is added.
         */
        public Builder addPayloadItem(XmlElement payloadItem) {
            Objects.requireNonNull(payloadItem, "Payload item MUST NOT be null.");
            this.payloadItems.add(checkForIllegalPayloadsAndPossiblyThrow(payloadItem));
            return this;
        }

        /**
         * Construct a content element from this builder.
         *
         * @return content element
         */
        public ContentElement build() {
            List<AffixElement> allAffixElements = collectAffixElements();
            PayloadElement payloadElement = new PayloadElement(payloadItems);
            return new ContentElement(payloadElement, allAffixElements);
        }

        private static XmlElement checkForIllegalPayloadsAndPossiblyThrow(XmlElement payloadItem) {
            QName qName = payloadItem.getQName();
            if (BLACKLISTED_QNAMES.contains(qName)) {
                throw new IllegalArgumentException("Element identified by " + qName +
                        " is not allowed as payload item. See https://xmpp.org/extensions/xep-0420.html#server-processed");
            }

            String namespace = payloadItem.getNamespace();
            if (BLACKLISTED_NAMESPACES.contains(namespace)) {
                throw new IllegalArgumentException("Elements of namespace '" + namespace +
                        "' are not allowed as payload items. See https://xmpp.org/extensions/xep-0420.html#server-processed");
            }

            return payloadItem;
        }

        private List<AffixElement> collectAffixElements() {
            List<AffixElement> allAffixElements = new ArrayList<>(Arrays.asList(rpad, from, timestamp));
            allAffixElements.addAll(otherAffixElements);
            return allAffixElements;
        }
    }
}