# PublicKeyProtectionPolicy.java

    /*
     * Licensed to the Apache Software Foundation (ASF) under one or more
     * contributor license agreements.  See the NOTICE file distributed with
     * this work for additional information regarding copyright ownership.
     * The ASF licenses this file to You 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.apache.pdfbox.pdmodel.encryption;

    import java.security.cert.X509Certificate;
    import java.util.ArrayList;
    import java.util.Iterator;
    import java.util.List;

    /**
     * The protection policy to use to protect a document with the public key security handler.
     *
     * PDF documents are encrypted so that they can be decrypted by
     * one or more recipients. Each recipient have its own access permission.
     *
     * The following code sample shows how to protect a document using
     * the public key security handler. In this code sample, <code>doc</code> is
     * a <code>PDDocument</code> object.
     *
     * <pre>
     * PublicKeyProtectionPolicy policy = new PublicKeyProtectionPolicy();
     * PublicKeyRecipient recip = new PublicKeyRecipient();
     * AccessPermission ap = new AccessPermission();
     * ap.setCanModify(false);
     * recip.setPermission(ap);
     *
     * // load the recipient's certificate
     * InputStream inStream = new FileInputStream(certificate_path);
     * CertificateFactory cf = CertificateFactory.getInstance("X.509");
     * X509Certificate certificate = (X509Certificate)cf.generateCertificate(inStream);
     * inStream.close();
     *
     * recip.setX509(certificate); // set the recipient's certificate
     * policy.addRecipient(recip);
     * policy.setEncryptionKeyLength(128); // the document will be encrypted with 128 bits secret key
     * doc.protect(policy);
     * doc.save(out);
     * </pre>
     *
     * @see org.apache.pdfbox.pdmodel.PDDocument#protect(ProtectionPolicy)
     * @see AccessPermission
     * @see PublicKeyRecipient
     * @author Benoit Guillon
     */
    public final class PublicKeyProtectionPolicy extends ProtectionPolicy
    {
        private final List<PublicKeyRecipient> recipients = new ArrayList<>();
        private X509Certificate decryptionCertificate;

        /**
         * Creates a new PublicKeyProtectionPolicy with an empty recipients list.
         */
        public PublicKeyProtectionPolicy()
        {
        }

        /**
         * Adds a new recipient to the recipients list.
         * @param recipient A new recipient.
         */
        public void addRecipient(PublicKeyRecipient recipient)
        {
            recipients.add(recipient);
        }

        /**
         * Removes a recipient from the recipients list.
         * @param recipient The recipient to remove.
         * @return true If a recipient was found and removed.
         */
        public boolean removeRecipient(PublicKeyRecipient recipient)
        {
            return recipients.remove(recipient);
        }

        /**
         * Returns an iterator to browse the list of recipients.
         * Object found in this iterator are <code>PublicKeyRecipient</code>.
         * @return The recipients list iterator.
         */
        public Iterator<PublicKeyRecipient> getRecipientsIterator()
        {
            return recipients.iterator();
        }

        /**
         * Returns the decryption certificate.
         * @return the decryption certificate
         */
        public X509Certificate getDecryptionCertificate()
        {
            return decryptionCertificate;
        }

        /**
         * Sets the decryption certificate
         * @param decryptionCertificate the new decryption certificate.
         */
        public void setDecryptionCertificate(X509Certificate decryptionCertificate)
        {
            this.decryptionCertificate = decryptionCertificate;
        }

        /**
         * Returns the number of recipients
         * @return the number of recipients
         */
        public int getNumberOfRecipients()
        {
            return recipients.size();
        }
    }