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
      • sign

        byte[] sign​(byte[] digest)
             throws IOException,

        Actually sign the digest 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 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 digest, 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.

        digest - the digest to sign, or null if it's a test run to determine sie.
        the signed object, as determined by the mode of this object
      • getTimeStampResp

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

        Return an ASN.1 encoded "TimeStampResp" (as defined in RFC3161) to be embedded in the PKCS#7 object, or null if no TimeStampResp is available. 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.

        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
        digest - the digest to sign, or null if it's a dummy.
        null to mean "no timestamp", a zero-byte array to mean "timestamp of unknown size", or a non-zero byte array which is the TimeStamp response
      • 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.