Package org.faceless.pdf2

Interface PKCS7SignatureHandler.SigningEngine

    • Method Detail

      • getMessageDigest

        MessageDigest getMessageDigest()
                        throws NoSuchAlgorithmException
        Return a new MessageDigest to be used to compute the signature. This will be called once per signature. Note in 2.28 the "throws NoSuchAlgorithmException" was added to the method signature
        Throws:
        NoSuchAlgorithmException

      • sign

        byte[] sign​(byte[] data)
     throws IOException,
            GeneralSecurityException

        Actually sign the supplier data and returned the signature.

        The exact format of the returned item will vary depending on the getType(), but is typically the output of the Signature.sign() method. For RSA signatures this equates to rsa(pad(DigestInfo)), which is effectively rsa(pad(asn1sequence(asn1sequence(algorithm, NULL), digest))), where rsa is the RSA algorithm, pad is the PKCS#1 1.5 padding algorithm, algorithm is the hash algorithm OID, and digest is an ASN.1 Octet string representing the digest of the data supplied to this method.

        The one exception to this is if getType() returns PKCS7SignatureHandler.SigningEngine.Type.PKCS7_COMPLETE, in which case this method should return the entire PKCS#7 object to embed in the PDF.

        This method may be called with a null argument for the data, in which case the API is attempting to determine the size of the signed object for space allocation in the final PDF. If an accurate estimate can be made, the returned array should be of the correct length (the contents of the array do not matter in this case). If no estimate can be made this method should return a zero-length array.

        Note that prior to 2.28.7, the API docs incorrectly described the parameter as the "digest". It is not the digest, it is the data to digest.

        Parameters:
        data - the data to sign, or null if it's a test run to determine size.
        Returns:
        the signed object, as determined by the mode of this object
        Throws:
        IOException
        GeneralSecurityException

      • getTimeStampResp

        byte[] getTimeStampResp​(byte[] digest)
                 throws IOException,
                        GeneralSecurityException

        Return an ASN.1 encoded "TimeStampResp" (as defined in RFC3161) to be embedded in the PKCS#7 object, or null if the signing process should use the default method for getting timestamps, i.e. retrieving them from the AcrobatSignatureHandelrFactory#getTimeStampServers. Most implementations will simply return null here.

        Like sign(byte[]), this method may be called with a null digest - if so the size of the returned array will be used to estimate how much space to allocate in the PDF. If this is not known, a zero-byte array should be returned.

        To help clarify this, here's a list of the possible inputs and outputs to this method, and what they mean.

        inputoutputexplanation
        nullnullthe API is trying to find out how big a TimeStamp would be if we were signing, and the null response means "there will be no timestamp"
        nullbyte[0]the API is trying to find out how big a TimeStamp would be if we were signing, and the zero-length response means "there will be a timestamp, but the only way to know how big it will be is it sign something"
        nullbyte[n]  the API is trying to find out how big a TimeStamp would be if we were signing, and the non-zero-length response means "there will be a timestamp, and it will be the same size as this byte array"
        byte[n]nullthis is a real TimeStamp request. The null response means this signature is not timestamped
        byte[n]byte[n]this is a real TimeStamp request. The non-zero-length response is the actual TimeStamp to embed

        Note that prior to 2.28.7 a return value of "null" meant "no timestamp", not "ask the factory"

        Parameters:
        digest - the digest to sign, or null if it's a dummy.
        Returns:
        null to mean "ask the factory", a zero-byte array to mean "timestamp of unknown size", or a non-zero byte array which is the TimeStamp response
        Throws:
        IOException
        GeneralSecurityException

      • getDigestEncryptionAlgorithm

        String getDigestEncryptionAlgorithm()
        Return the Digest Encryption algorithm of the signature returned from sign(byte[]), eg "SHA1withRSA", "SHA1withDSA", "SHA256withECDSA", or an ASN.1 OID representing the same, eg "1.2.840.113549.1.1.5".

      • setPassword

        void setPassword​(PasswordCallback callback)
        Set the password on the suppled PasswordCallback. This is required because some types of PKCS#11 token require a second login immediately before the "sign" call. For SigningEngines unconcerned with PKCS#11, this method can be a no-op.
        Since:
        2.25