Module org.apache.santuario.xmlsec
Package org.apache.xml.security.signature

Class XMLSignature

  • public final class XMLSignature
extends SignatureElementProxy
    Handles <ds:Signature> elements. This is the main class that deals with creating and verifying signatures.

    There are 2 types of constructors for this class. The ones that take a document, baseURI and 1 or more Java Objects. This is mostly used for signing purposes. The other constructor is the one that takes a DOM Element and a baseURI. This is used mostly with for verifying, when you have a SignatureElement. There are a few different types of methods:

    • The addDocument* methods are used to add References with optional transforms during signing.
    • addKeyInfo* methods are to add Certificates and Keys to the KeyInfo tags during signing.
    • appendObject allows a user to add any XML Structure as an ObjectContainer during signing.
    • sign and checkSignatureValue methods are used to sign and validate the signature.

    • Field Detail

      • ALGO_ID_SIGNATURE_DSA

        public static final String ALGO_ID_SIGNATURE_DSA
        Signature - Required DSAwithSHA1 (DSS)
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_DSA_SHA256

        public static final String ALGO_ID_SIGNATURE_DSA_SHA256
        Signature - Optional DSAwithSHA256
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA

        public static final String ALGO_ID_SIGNATURE_RSA
        Signature - Recommended RSAwithSHA1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA1
        Signature - Recommended RSAwithSHA1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_NOT_RECOMMENDED_RSA_MD5

        public static final String ALGO_ID_SIGNATURE_NOT_RECOMMENDED_RSA_MD5
        Signature - NOT Recommended RSAwithMD5
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_RIPEMD160

        public static final String ALGO_ID_SIGNATURE_RSA_RIPEMD160
        Signature - Optional RSAwithRIPEMD160
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA224

        public static final String ALGO_ID_SIGNATURE_RSA_SHA224
        Signature - Optional RSAwithSHA224
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA256

        public static final String ALGO_ID_SIGNATURE_RSA_SHA256
        Signature - Optional RSAwithSHA256
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA384

        public static final String ALGO_ID_SIGNATURE_RSA_SHA384
        Signature - Optional RSAwithSHA384
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA512

        public static final String ALGO_ID_SIGNATURE_RSA_SHA512
        Signature - Optional RSAwithSHA512
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA1_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA1_MGF1
        Signature - Optional RSAwithSHA1andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA224_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA224_MGF1
        Signature - Optional RSAwithSHA224andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA256_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA256_MGF1
        Signature - Optional RSAwithSHA256andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA384_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA384_MGF1
        Signature - Optional RSAwithSHA384andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA512_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA512_MGF1
        Signature - Optional RSAwithSHA512andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA3_224_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA3_224_MGF1
        Signature - Optional RSAwithSHA3_224andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA3_256_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA3_256_MGF1
        Signature - Optional RSAwithSHA3_256andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA3_384_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA3_384_MGF1
        Signature - Optional RSAwithSHA3_384andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_SHA3_512_MGF1

        public static final String ALGO_ID_SIGNATURE_RSA_SHA3_512_MGF1
        Signature - Optional RSAwithSHA3_512andMGF1
        See Also:
        Constant Field Values

      • ALGO_ID_MAC_HMAC_NOT_RECOMMENDED_MD5

        public static final String ALGO_ID_MAC_HMAC_NOT_RECOMMENDED_MD5
        HMAC - NOT Recommended HMAC-MD5
        See Also:
        Constant Field Values

      • ALGO_ID_MAC_HMAC_RIPEMD160

        public static final String ALGO_ID_MAC_HMAC_RIPEMD160
        HMAC - Optional HMAC-RIPEMD160
        See Also:
        Constant Field Values

      • ALGO_ID_MAC_HMAC_SHA224

        public static final String ALGO_ID_MAC_HMAC_SHA224
        HMAC - Optional HMAC-SHA2224
        See Also:
        Constant Field Values

      • ALGO_ID_MAC_HMAC_SHA256

        public static final String ALGO_ID_MAC_HMAC_SHA256
        HMAC - Optional HMAC-SHA256
        See Also:
        Constant Field Values

      • ALGO_ID_MAC_HMAC_SHA384

        public static final String ALGO_ID_MAC_HMAC_SHA384
        HMAC - Optional HMAC-SHA284
        See Also:
        Constant Field Values

      • ALGO_ID_MAC_HMAC_SHA512

        public static final String ALGO_ID_MAC_HMAC_SHA512
        HMAC - Optional HMAC-SHA512
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_ECDSA_SHA1

        public static final String ALGO_ID_SIGNATURE_ECDSA_SHA1
        Signature - Optional ECDSAwithSHA1
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_ECDSA_SHA224

        public static final String ALGO_ID_SIGNATURE_ECDSA_SHA224
        Signature - Optional ECDSAwithSHA224
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_ECDSA_SHA256

        public static final String ALGO_ID_SIGNATURE_ECDSA_SHA256
        Signature - Optional ECDSAwithSHA256
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_ECDSA_SHA384

        public static final String ALGO_ID_SIGNATURE_ECDSA_SHA384
        Signature - Optional ECDSAwithSHA384
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_ECDSA_SHA512

        public static final String ALGO_ID_SIGNATURE_ECDSA_SHA512
        Signature - Optional ECDSAwithSHA512
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_ECDSA_RIPEMD160

        public static final String ALGO_ID_SIGNATURE_ECDSA_RIPEMD160
        Signature - Optional ECDSAwithRIPEMD160
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_EDDSA_ED25519

        public static final String ALGO_ID_SIGNATURE_EDDSA_ED25519
        Signature - EDDSA ED25519
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_EDDSA_ED448

        public static final String ALGO_ID_SIGNATURE_EDDSA_ED448
        Signature - EDDSA ED448
        See Also:
        Constant Field Values

      • ALGO_ID_SIGNATURE_RSA_PSS

        public static final String ALGO_ID_SIGNATURE_RSA_PSS
        Signature - Optional RSASSA-PSS
        See Also:
        Constant Field Values

    • Constructor Detail

      • XMLSignature

        public XMLSignature​(Document doc,
                    String baseURI,
                    String signatureMethodURI)
             throws XMLSecurityException
        This creates a new ds:Signature Element and adds an empty ds:SignedInfo. The ds:SignedInfo is initialized with the specified Signature algorithm and Canonicalizer.ALGO_ID_C14N_OMIT_COMMENTS which is REQUIRED by the spec. This method's main use is for creating a new signature.
        Parameters:
        doc - Document in which the signature will be appended after creation.
        baseURI - URI to be used as context for all relative URIs.
        signatureMethodURI - signature algorithm to use.
        Throws:
        XMLSecurityException

      • XMLSignature

        public XMLSignature​(Document doc,
                    String baseURI,
                    String signatureMethodURI,
                    Provider provider)
             throws XMLSecurityException
        This creates a new ds:Signature Element and adds an empty ds:SignedInfo. The ds:SignedInfo is initialized with the specified Signature algorithm and Canonicalizer.ALGO_ID_C14N_OMIT_COMMENTS which is REQUIRED by the spec. This method's main use is for creating a new signature.
        Parameters:
        doc - Document in which the signature will be appended after creation.
        baseURI - URI to be used as context for all relative URIs.
        signatureMethodURI - signature algorithm to use.
        provider - security provider to use.
        Throws:
        XMLSecurityException

      • XMLSignature

        public XMLSignature​(Document doc,
                    String baseURI,
                    String signatureMethodURI,
                    int hmacOutputLength)
             throws XMLSecurityException
        Constructor XMLSignature
        Parameters:
        doc - Document in which the signature will be appended after creation.
        baseURI - URI to be used as context for all relative URIs.
        signatureMethodURI - the Signature method to be used.
        hmacOutputLength -
        Throws:
        XMLSecurityException

      • XMLSignature

        public XMLSignature​(Document doc,
                    String baseURI,
                    String signatureMethodURI,
                    int hmacOutputLength,
                    Provider provider)
             throws XMLSecurityException
        Constructor XMLSignature
        Parameters:
        doc - Document in which the signature will be appended after creation.
        baseURI - URI to be used as context for all relative URIs.
        signatureMethodURI - the Signature method to be used.
        hmacOutputLength -
        provider - security provider to use.
        Throws:
        XMLSecurityException

      • XMLSignature

        public XMLSignature​(Document doc,
                    String baseURI,
                    String signatureMethodURI,
                    String canonicalizationMethodURI)
             throws XMLSecurityException
        Constructor XMLSignature
        Parameters:
        doc - Document in which the signature will be appended after creation.
        baseURI - URI to be used as context for all relative URIs.
        signatureMethodURI - the Signature method to be used.
        canonicalizationMethodURI - the canonicalization algorithm to be used to c14nize the SignedInfo element.
        Throws:
        XMLSecurityException

      • XMLSignature

        public XMLSignature​(Document doc,
                    String baseURI,
                    String signatureMethodURI,
                    String canonicalizationMethodURI,
                    Provider provider)
             throws XMLSecurityException
        Constructor XMLSignature
        Parameters:
        doc - Document in which the signature will be appended after creation.
        baseURI - URI to be used as context for all relative URIs.
        signatureMethodURI - the Signature method to be used.
        canonicalizationMethodURI - the canonicalization algorithm to be used to c14nize the SignedInfo element.
        provider - security provider to use.
        Throws:
        XMLSecurityException

      • XMLSignature

        public XMLSignature​(Document doc,
                    String baseURI,
                    String signatureMethodURI,
                    int hmacOutputLength,
                    String canonicalizationMethodURI)
             throws XMLSecurityException
        Constructor XMLSignature
        Parameters:
        doc - Document in which the signature will be appended after creation.
        baseURI - URI to be used as context for all relative URIs.
        signatureMethodURI - the Signature method to be used.
        hmacOutputLength -
        canonicalizationMethodURI - the canonicalization algorithm to be used to c14nize the SignedInfo element.
        Throws:
        XMLSecurityException

      • XMLSignature

        public XMLSignature​(Document doc,
                    String baseURI,
                    String signatureMethodURI,
                    int hmacOutputLength,
                    String canonicalizationMethodURI,
                    Provider provider,
                    AlgorithmParameterSpec spec)
             throws XMLSecurityException
        Constructor XMLSignature
        Parameters:
        doc - Document in which the signature will be appended after creation.
        baseURI - URI to be used as context for all relative URIs.
        signatureMethodURI - the Signature method to be used.
        hmacOutputLength -
        canonicalizationMethodURI - the canonicalization algorithm to be used to c14nize the SignedInfo element.
        provider - security provider to use.
        spec -
        Throws:
        XMLSecurityException

      • XMLSignature

        public XMLSignature​(Element element,
                    String baseURI,
                    boolean secureValidation)
             throws XMLSignatureException,
                    XMLSecurityException
        This will parse the element and construct the Java Objects. That will allow a user to validate the signature.
        Parameters:
        element - ds:Signature element that contains the whole signature
        baseURI - URI to be prepended to all relative URIs
        secureValidation - whether secure secureValidation is enabled or not
        Throws:
        XMLSecurityException
        XMLSignatureException - if the signature is badly formatted

      • XMLSignature

        public XMLSignature​(Element element,
                    String baseURI,
                    boolean secureValidation,
                    Provider provider)
             throws XMLSignatureException,
                    XMLSecurityException
        This will parse the element and construct the Java Objects. That will allow a user to validate the signature.
        Parameters:
        element - ds:Signature element that contains the whole signature
        baseURI - URI to be prepended to all relative URIs
        secureValidation - whether secure secureValidation is enabled or not
        provider - security provider to use
        Throws:
        XMLSecurityException
        XMLSignatureException - if the signature is badly formatted

    • Method Detail

      • setId

        public void setId​(String id)
        Sets the Id attribute
        Parameters:
        id - Id value for the id attribute on the Signature Element

      • getId

        public String getId()
        Returns the Id attribute
        Returns:
        the Id attribute

      • getSignedInfo

        public SignedInfo getSignedInfo()
        Returns the completely parsed SignedInfo object.
        Returns:
        the completely parsed SignedInfo object.

      • getSignatureValue

        public byte[] getSignatureValue()
                         throws XMLSignatureException
        Returns the octet value of the SignatureValue element. Throws an XMLSignatureException if it has no or wrong content.
        Returns:
        the value of the SignatureValue element.
        Throws:
        XMLSignatureException - If there is no content

      • getKeyInfo

        public KeyInfo getKeyInfo()
        Returns the KeyInfo child. If we are in signing mode and the KeyInfo does not exist yet, it is created on demand and added to the Signature.
        This allows to add arbitrary content to the KeyInfo during signing.
        Returns:
        the KeyInfo object

      • appendObject

        public void appendObject​(ObjectContainer object)
                  throws XMLSignatureException
        Appends an Object (not a java.lang.Object but an Object element) to the Signature. Please note that this is only possible when signing.
        Parameters:
        object - ds:Object to be appended.
        Throws:
        XMLSignatureException - When this object is used to verify.

      • getObjectItem

        public ObjectContainer getObjectItem​(int i)
        Returns the ith ds:Object child of the signature or null if no such ds:Object element exists.
        Parameters:
        i -
        Returns:
        the ith ds:Object child of the signature or null if no such ds:Object element exists.

      • getObjectLength

        public int getObjectLength()
        Returns the number of all ds:Object elements.
        Returns:
        the number of all ds:Object elements.

      • checkSignatureValue

        public boolean checkSignatureValue​(X509Certificate cert)
                            throws XMLSignatureException
        Extracts the public key from the certificate and verifies if the signature is valid by re-digesting all References, comparing those against the stored DigestValues and then checking to see if the Signatures match on the SignedInfo.
        Parameters:
        cert - Certificate that contains the public key part of the keypair that was used to sign.
        Returns:
        true if the signature is valid, false otherwise
        Throws:
        XMLSignatureException

      • checkSignatureValue

        public boolean checkSignatureValue​(Key pk)
                            throws XMLSignatureException
        Verifies if the signature is valid by redigesting all References, comparing those against the stored DigestValues and then checking to see if the Signatures match on the SignedInfo.
        Parameters:
        pk - PublicKey part of the keypair or SecretKey that was used to sign
        Returns:
        true if the signature is valid, false otherwise
        Throws:
        XMLSignatureException

      • addDocument

        public void addDocument​(String referenceURI,
                        Transforms trans,
                        String digestURI,
                        String referenceId,
                        String referenceType)
                 throws XMLSignatureException
        Add a Reference with full parameters to this Signature
        Parameters:
        referenceURI - URI of the resource to be signed. Can be null in which case the dereferencing is application specific. Can be "" in which it's the parent node (or parent document?). There can only be one "" in each signature.
        trans - Optional list of transformations to be done before digesting
        digestURI - Mandatory URI of the digesting algorithm to use.
        referenceId - Optional id attribute for this Reference
        referenceType - Optional mimetype for the URI
        Throws:
        XMLSignatureException

      • addDocument

        public void addDocument​(String referenceURI,
                        Transforms trans)
                 throws XMLSignatureException
        Adds a Reference with just the URI and the transforms. This used the SHA1 algorithm as a default digest algorithm.
        Parameters:
        referenceURI - URI according to the XML Signature specification.
        trans - List of transformations to be applied.
        Throws:
        XMLSignatureException

      • addDocument

        public void addDocument​(String referenceURI)
                 throws XMLSignatureException
        Add a Reference with just this URI. It uses SHA1 by default as the digest algorithm
        Parameters:
        referenceURI - URI according to the XML Signature specification.
        Throws:
        XMLSignatureException

      • addKeyInfo

        public void addKeyInfo​(X509Certificate cert)
                throws XMLSecurityException
        Add an X509 Certificate to the KeyInfo. This will include the whole cert inside X509Data/X509Certificate tags.
        Parameters:
        cert - Certificate to be included. This should be the certificate of the key that was used to sign.
        Throws:
        XMLSecurityException

      • addKeyInfo

        public void addKeyInfo​(PublicKey pk)
        Add this public key to the KeyInfo. This will include the complete key in the KeyInfo structure.
        Parameters:
        pk -

      • setFollowNestedManifests

        public void setFollowNestedManifests​(boolean followManifests)
        Signal whether Manifest should be automatically validated. Checking the digests in References in a Signature are mandatory, but for References inside a Manifest it is application specific. This boolean is to indicate that the References inside Manifests should be validated.
        Parameters:
        followManifests -
        See Also:
        Core validation section in the XML Signature Rec.

      • getBaseLocalName

        public String getBaseLocalName()
        Get the local name of this element
        Specified by:
        getBaseLocalName in class ElementProxy
        Returns:
        Constants._TAG_SIGNATURE