Package com.ironcorelabs.sdk

Class IronSdk

  • public final class IronSdk
extends java.lang.Object
    Struct that is used to make authenticated requests to the IronCore API. Instantiated with the details of an accounts various ids, device, and signing keys. Once instantiated all operations will be performed in the context of the account provided.

    • Method Detail

      • userVerify

        public static java.util.Optional<UserVerifyResult> userVerify​(java.lang.String jwt)
                                                       throws java.lang.Exception
        Verify a user given a JWT for their user record.
        Parameters:
        jwt - valid IronCore JWT
        Returns:
        option of whether the user's account record exists in the IronCore system or not. Error if the request couldn't be made.
        Throws:
        java.lang.Exception

      • userCreate

        public static UserCreateResult userCreate​(java.lang.String jwt,
                                          java.lang.String password,
                                          UserCreateOpts options)
                                   throws java.lang.Exception
        Create a new user within the IronCore system.
        Parameters:
        jwt - valid IronCore or Auth0 JWT
        password - password used to encrypt and escrow the user's private master key
        options - see UserCreateOpts. Use `new UserCreateOpts()` for defaults
        Returns:
        see UserCreateResult. For most use cases, the public key can be discarded as IronCore escrows your user's keys. The escrowed keys are unlocked by the provided password.
        Throws:
        java.lang.Exception

      • initialize

        public static IronSdk initialize​(DeviceContext init)
                          throws java.lang.Exception
        Initialize IronSdk with a device. Verifies that the provided user/segment exists and the provided device keys are valid and exist for the provided account.
        Parameters:
        init - device context used to initialize the IronSdk with a set of device keys
        Returns:
        an instance of the IronSdk
        Throws:
        java.lang.Exception - if the provided `DeviceContext` is invalid

      • generateNewDevice

        public static DeviceContext generateNewDevice​(java.lang.String jwt,
                                              java.lang.String password,
                                              DeviceCreateOpts deviceCreateOptions)
                                       throws java.lang.Exception
        Generates a new device for the user specified in the signed JWT. This will result in a new transform key (from the user's master private key to the new device's public key) being generated and stored with the IronCore Service.
        Parameters:
        jwt - valid IronCore JWT
        password - password used to encrypt and escrow the user's private key
        deviceCreateOptions - optional values, like device name
        Returns:
        details about the newly created device
        Throws:
        java.lang.Exception

      • advanced

        public final IronSdkAdvanced advanced()
        Access advanced SDK operations.
        Returns:
        an instance of the IronSdkAdvanced

      • userListDevices

        public final UserDeviceListResult userListDevices()
                                           throws java.lang.Exception
        Get all the devices for the current user
        Returns:
        all devices for the current user, sorted by the device id
        Throws:
        java.lang.Exception

      • userGetPublicKey

        public final UserWithKey[] userGetPublicKey​(UserId[] users)
                                     throws java.lang.Exception
        Get a list of user public keys given their IDs. Allows discovery of which user IDs have keys in the IronCore system to determine of they can be added to groups or have documents shared with them.AsMut
        Parameters:
        users - list of user IDs to check
        Returns:
        map from user ID to users public key. Only users who have public keys will be returned in the map
        Throws:
        java.lang.Exception

      • userDeleteDevice

        public final DeviceId userDeleteDevice​(DeviceId deviceId)
                                throws java.lang.Exception
        Delete a user device. If deleting the currently signed in device (None for `deviceId`), the sdk will need to be reinitialized with `IronSdk.initialize()` before further use.
        Parameters:
        deviceId - id of the device to delete. If `null`, delete the currently signed in device userListDevices() to get ids
        Returns:
        id of deleted device or IronSdkErr
        Throws:
        java.lang.Exception

      • documentList

        public final DocumentListResult documentList()
                                      throws java.lang.Exception
        List all of the documents that the current user is able to decrypt.
        Returns:
        DocumentListResult struct with vec of metadata about each document the user can decrypt.
        Throws:
        java.lang.Exception

      • documentGetMetadata

        public final DocumentMetadataResult documentGetMetadata​(DocumentId id)
                                                 throws java.lang.Exception
        Get the metadata for a specific document given its id.
        Parameters:
        id - unique id of the document to retrieve
        Returns:
        DocumentMetadataResult with details about the requested document.
        Throws:
        java.lang.Exception

      • documentGetIdFromBytes

        public final DocumentId documentGetIdFromBytes​(byte[] encryptedDocument)
                                        throws java.lang.Exception
        Attempt to parse the document id out of an encrypted document.
        Parameters:
        encryptedDocument - encrypted document bytes
        Returns:
        extracted id
        Throws:
        java.lang.Exception - if provided encrypted document has no header

      • documentEncrypt

        public final DocumentEncryptResult documentEncrypt​(byte[] documentData,
                                                   DocumentEncryptOpts encryptOpts)
                                            throws java.lang.Exception
        Encrypt the provided document bytes.
        Parameters:
        documentData - bytes of the document to encrypt
        encryptOpts - optional document encrypt parameters
        Throws:
        java.lang.Exception

      • documentUpdateBytes

        public final DocumentEncryptResult documentUpdateBytes​(DocumentId id,
                                                       byte[] newDocumentData)
                                                throws java.lang.Exception
        Update the encrypted content of an existing document. Persists any existing access to other users and groups.
        Parameters:
        id - id of document to update
        newDocumentData - updated document content to encrypt
        Throws:
        java.lang.Exception

      • documentDecrypt

        public final DocumentDecryptResult documentDecrypt​(byte[] encryptedDocument)
                                            throws java.lang.Exception
        Decrypts the provided encrypted document and returns details about the document as well as its decrypted bytes.
        Parameters:
        encryptedDocument - bytes of encrypted document. Should be the same bytes returned from documentEncrypt(byte[], DocumentEncryptOpts)
        Returns:
        DocumentDecryptResult includes metadata about the provided document as well as the decrypted document bytes
        Throws:
        java.lang.Exception

      • documentUpdateName

        public final DocumentMetadataResult documentUpdateName​(DocumentId id,
                                                       DocumentName name)
                                                throws java.lang.Exception
        Update a document name to a new value or clear its value.
        Parameters:
        id - id of the document to update
        name - new name for the document. Provide a DocumentName to update to a new name or `null` to clear the name field
        Returns:
        metadata about the document that was updated.
        Throws:
        java.lang.Exception

      • documentGrantAccess

        public final DocumentAccessResult documentGrantAccess​(DocumentId documentId,
                                                      UserId[] userGrants,
                                                      GroupId[] groupGrants)
                                               throws java.lang.Exception
        Grant access to a document. Recipients of document access can be either users or groups.
        Parameters:
        documentId - id of the document whose access is is being modified
        userGrants - list of user grants
        groupGrants - list of group grants
        Returns:
        each individual grant to a user/group succeeded or failed
        Throws:
        java.lang.Exception - the request failed either on the client or the server rejected the whole request

      • documentRevokeAccess

        public final DocumentAccessResult documentRevokeAccess​(DocumentId documentId,
                                                       UserId[] userRevokes,
                                                       GroupId[] groupRevokes)
                                                throws java.lang.Exception
        Revoke access from a document. Revocation of document access can be either users or groups.
        Parameters:
        documentId - id of the document whose access is is being modified
        userRevokes - list of user revokes
        groupRevokes - list of group revokes
        Returns:
        each individual revoke from a user/group either succeeded or failed
        Throws:
        java.lang.Exception - the request failed either on the client or the server rejected the whole request

      • groupList

        public final GroupListResult groupList()
                                throws java.lang.Exception
        List all of the groups that the current user is either an admin or member of.
        Returns:
        list of (abbreviated) metadata about each group the user is a part of
        Throws:
        java.lang.Exception

      • groupGetMetadata

        public final GroupGetResult groupGetMetadata​(GroupId id)
                                      throws java.lang.Exception
        Get the full metadata for a specific group given its ID.
        Parameters:
        id - unique id of the group to retrieve
        Returns:
        details about the requested group
        Throws:
        java.lang.Exception

      • groupCreate

        public final GroupMetaResult groupCreate​(GroupCreateOpts groupCreateOpts)
                                  throws java.lang.Exception
        Create a group. The creating user will become a group admin.
        Parameters:
        groupCreateOpts - see GroupCreateOpts. Use `new GroupCreateOpts()` for defaults
        Throws:
        java.lang.Exception

      • groupUpdateName

        public final GroupMetaResult groupUpdateName​(GroupId id,
                                             GroupName name)
                                      throws java.lang.Exception
        Update a group name to a new value or clear its value.
        Parameters:
        id - id of the group to update
        name - new name for the group. Provide a GroupName to update to a new name or `null` to clear the name field
        Returns:
        metadata about the group that was updated
        Throws:
        java.lang.Exception

      • groupDelete

        public final GroupId groupDelete​(GroupId id)
                          throws java.lang.Exception
        Delete the identified group.
        Parameters:
        id - unique id of group
        Returns:
        the deleted group id
        Throws:
        java.lang.Exception - if it wasn't able to delete the group

      • groupAddMembers

        public final GroupAccessEditResult groupAddMembers​(GroupId id,
                                                   UserId[] users)
                                            throws java.lang.Exception
        Add the users as members of a group.
        Parameters:
        id - id of the group to add members to
        users - the list of users thet will be added to the group as members
        Returns:
        all the users that were added and all the users that were not added with the reason they were not
        Throws:
        java.lang.Exception

      • groupRemoveMembers

        public final GroupAccessEditResult groupRemoveMembers​(GroupId id,
                                                      UserId[] userRevokes)
                                               throws java.lang.Exception
        Remove a list of users as members from the group.
        Parameters:
        id - id of the group to remove members from
        userRevokes - list of user ids to remove as members
        Returns:
        list of users that were removed and the users that failed to be removed with the reason they were not
        Throws:
        java.lang.Exception

      • groupAddAdmins

        public final GroupAccessEditResult groupAddAdmins​(GroupId id,
                                                  UserId[] users)
                                           throws java.lang.Exception
        Add the users as admins of a group.
        Parameters:
        id - id of the group to add admins to
        users - the list of users that will be added to the group as admins
        Returns:
        all the users that were added and the users that were not added with the reason they were not
        Throws:
        java.lang.Exception

      • groupRemoveAdmins

        public final GroupAccessEditResult groupRemoveAdmins​(GroupId id,
                                                     UserId[] userRevokes)
                                              throws java.lang.Exception
        Remove a list of users as admins from the group.
        Parameters:
        id - id of the group
        userRevokes - list of user ids to remove as admins
        Returns:
        list of users that were removed and the users that failed to be removed with the reason they were not
        Throws:
        java.lang.Exception

      • delete

        public void delete()

      • finalize

        protected void finalize()
                 throws java.lang.Throwable
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable