Interface PKCS7SignatureHandler.SigningEngine

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Interface Description
      static class  PKCS7SignatureHandler.SigningEngine.Type
      An enum that determine which type of PKCS7 Signature structure will be embedded with a SigningEngine
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      java.util.List<java.security.cert.X509Certificate> getCertificates()
      Return the full list of X.509 certificates to be embedded into the signature.
      java.util.List<java.security.cert.X509CRL> getCRLs()
      Return a list of X.509 CRL objects that should be used if required, or null.
      java.lang.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".
      java.security.MessageDigest getMessageDigest()
      Return a new MessageDigest to be used to compute the signature.
      java.util.List<PKCS7SignatureHandler.OCSPResponse> getOCSPResponses()
      Return a list of OCSP responses that should be used if required, or null.
      byte[] getTimeStampResp​(byte[] digest)
      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.
      PKCS7SignatureHandler.SigningEngine.Type getType()
      Return the type of object returned from the sign(byte[]) method
      void setPassword​(javax.security.auth.callback.PasswordCallback callback)
      Set the password on the suppled PasswordCallback.
      byte[] sign​(byte[] digest)
      Actually sign the digest and returned the signature.
    • Method Detail

      • getMessageDigest

        java.security.MessageDigest getMessageDigest()
                                              throws java.security.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:
        java.security.NoSuchAlgorithmException
      • getCertificates

        java.util.List<java.security.cert.X509Certificate> getCertificates()
                                                                    throws java.io.IOException,
                                                                           java.security.GeneralSecurityException

        Return the full list of X.509 certificates to be embedded into the signature. This must include any certificates required to certify the signature up to the root certificate, and includes Certificates for any OCSP responders that would be queried as part of the Certificate verification process. The signing Certificate must be item 0 in the list.

        The one exception to this is if getType() returns PKCS7SignatureHandler.SigningEngine.Type.PKCS7_COMPLETE, in which case this method may return null.

        This method will be called multiple times, so the object returned from this method should be stored locally.

        Throws:
        java.io.IOException
        java.security.GeneralSecurityException
      • sign

        byte[] sign​(byte[] digest)
             throws java.io.IOException,
                    java.security.GeneralSecurityException

        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.

        Parameters:
        digest - the digest to sign, or null if it's a test run to determine sie.
        Returns:
        the signed object, as determined by the mode of this object
        Throws:
        java.io.IOException
        java.security.GeneralSecurityException
      • getTimeStampResp

        byte[] getTimeStampResp​(byte[] digest)
                         throws java.io.IOException,
                                java.security.GeneralSecurityException

        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.

        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
        Parameters:
        digest - the digest to sign, or null if it's a dummy.
        Returns:
        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
        Throws:
        java.io.IOException
        java.security.GeneralSecurityException
      • getDigestEncryptionAlgorithm

        java.lang.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​(javax.security.auth.callback.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
      • getOCSPResponses

        java.util.List<PKCS7SignatureHandler.OCSPResponse> getOCSPResponses()
                                                                     throws java.io.IOException,
                                                                            java.security.GeneralSecurityException
        Return a list of OCSP responses that should be used if required, or null.
        Throws:
        java.io.IOException
        java.security.GeneralSecurityException
        Since:
        2.28
      • getCRLs

        java.util.List<java.security.cert.X509CRL> getCRLs()
                                                    throws java.io.IOException,
                                                           java.security.GeneralSecurityException
        Return a list of X.509 CRL objects that should be used if required, or null.
        Throws:
        java.io.IOException
        java.security.GeneralSecurityException
        Since:
        2.28