Interface SignatureService


  • public interface SignatureService
    The service to create and retrieve signature information for files in the repository.

    Signatures represent a "stamp" for a specific user for a specific version of a file. For example, the signature can represent an approval (or disapproval) of a specific version of a file by a specific user. The signature can enable administrative users to track the viability of a version of a file through a loosely-defined approval process. The signature can be used to track an overall sign-off process that enables users to promote (or demote) specific files in a production environment. This is one example of the way that signatures can be used.

    Repository files can be either versioned or not versioned when they are signed. Containers cannot be signed.

    When an unversioned file is updated or deleted, all of the signatures are removed. Because signatures are tied to a specific version of a file, the signatures are linked to that content's lifecycle. When a new version of a versioned file is created, the signatures that are associated with the prior version are kept and are accessible because the prior version is maintained within the repository. If a versioned file is deleted, all of the signatures are removed.

    Since:
    1.7
    • Method Detail

      • getSignatureReasons

        java.util.Set<java.lang.String> getSignatureReasons()
        Gets all of the valid signature reasons that can be used to populate a CreateSignatureInfo object to create a signature. The set of reasons is configured on the server and is used to validate a signature.
        Returns:
        The set of valid signature reasons.
        Since:
        1.7
        See Also:
        createSignature(String, CreateSignatureInfo)
      • getSignatureRoles

        java.util.Set<java.lang.String> getSignatureRoles()
        Gets all of the valid signature roles that can be used to populate a CreateSignatureInfo object to create a signature. The set of roles is configured on the server and is used to validate a signature.
        Returns:
        The set of valid signature roles.
        Since:
        1.7
        See Also:
        createSignature(String, CreateSignatureInfo)
      • createSignature

        Signature createSignature​(java.lang.String path,
                                  CreateSignatureInfo createSignatureInfo)
                           throws AuthenticationException,
                                  SigningException
        Creates a signature for the current version of a file (only the current version of a file can be signed). The CreateSignatureInfo object must contain the valid credentials of the user who signs the file. The credentials are used to verify the authenticity of the signer, so issues that arise when authenticating the signer generate an AuthenticationException.

        The signing parameters supplied in the CreateSignatureInfo object are stored with the signature and are used to generate the signature value itself. The signature metadata not only describes the signature itself, it is used in the cryptography to generate the signature value. Therefore, the signature is self-describing and self-validating.

        The signature role that is specified on the CreateSignatureInfo object is required and must be a valid signing role that matches a value from getSignatureRoles(). The signature reason that is specified in the CreateSignatureInfo object is required and must be a valid signing reason that matches a value from getSignatureReasons().

        Parameters:
        path - The path to the file to sign.
        createSignatureInfo - The parameters to use to create the signature, which includes the credentials of the signer.
        Returns:
        The Signature object to create.
        Throws:
        AuthenticationException - Thrown when the credentials presented are incorrect or the account to use is locked, expired, or inactive.
        SigningException - Thrown when the signature generation process fails.
        Since:
        1.7
        See Also:
        getSignatureRoles(), getSignatureReasons()
      • getSigningStatus

        RepositoryFile.SigningStatus getSigningStatus​(java.lang.String path)
                                               throws RepositoryItemNotFoundException
        Describes the overall signature status of the file. If the file is versioned, the possible values are NONE, CURRENT, PREVIOUS, and CURRENT_AND_PREVIOUS. CURRENT means that the current version is signed and no previous version is signed. PREVIOUS means that at least one previous version of the file is signed and the current version is not signed. CURRENT_AND_PREVIOUS means that the current version is signed and at least one previous version is signed.

        If the file is not versioned, the possible values are NONE and CURRENT.

        Parameters:
        path - The path to the file.
        Throws:
        RepositoryItemNotFoundException - Thrown when the file does not exist.
        Since:
        2.1
      • isVersionSigned

        boolean isVersionSigned​(java.lang.String path,
                                java.lang.String version)
        Indicates whether a signatures exists for the specific version of a file. If the path does not exist, references an object that is not a file, or is for an unversioned file, then False is returned. The version must be a valid repository file version label, such as one returned by calling RepositoryFile.getVersion().
        Parameters:
        path - The path to the file.
        version - The version of the file.
        Returns:
        True, if signatures exist for the version of the file, False otherwise.
        Since:
        1.7
        See Also:
        RepositoryFile.getVersion()
      • getSignatures

        java.util.Set<Signature> getSignatures​(java.lang.String path)
                                        throws RepositoryItemNotFoundException
        Gets all of the signatures that are associated with a file. For an unversioned file, all of the current signatures are retrieved. For a versioned file, all of the signatures for all of the versions are retrieved. If the path is to a container, then an IllegalArgumentException is thrown because container objects cannot be signed.

        If the path does not exist, a RepositoryItemNotFoundException is thrown.

        Parameters:
        path - The path to the file.
        Returns:
        The set of signatures that correspond to all versions of the file.
        Throws:
        RepositoryItemNotFoundException - Thrown when the file does not exist.
        Since:
        1.7
      • getSignaturesForLatestVersion

        java.util.Set<Signature> getSignaturesForLatestVersion​(java.lang.String path)
                                                        throws RepositoryItemNotFoundException
        Gets all of the signatures for the latest version of a file. The file can be versioned or unversioned, the current version is used in both cases. If the path is to a container, then an IllegalArgumentException is thrown because container objects cannot be signed.

        If the path does not exist, a RepositoryItemNotFoundException is thrown.

        Parameters:
        path - The path to the file.
        Returns:
        The set of signatures that were created for the current version of the file.
        Throws:
        RepositoryItemNotFoundException - Thrown when the file does not exist.
        Since:
        1.7
      • getSignaturesByVersion

        java.util.Set<Signature> getSignaturesByVersion​(java.lang.String path,
                                                        java.lang.String version)
                                                 throws RepositoryItemNotFoundException
        Gets all of the the signatures for a specific version of a file. If the path is to a container, then an IllegalArgumentException is thrown because container objects cannot be signed. The version must be a valid repository file version label, such as RepositoryFile.getVersion() .

        If the path does not exist, or the version does not exist, then a RepositoryItemNotFoundException is thrown.

        Parameters:
        path - The path to the file.
        version - The version of the file.
        Returns:
        The set of signatures that were created for the version of the file.
        Throws:
        RepositoryItemNotFoundException - Thrown when the file or version does not exist.
        Since:
        1.7
        See Also:
        RepositoryFile.getVersion()