Protocol Documentation

Top

authn.proto

NOTE: This API is only exposed when the D1 service is configured to use the standalone ID provider.

AddUserToGroupsRequest

Represents the addition of a user to one or more groups.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
user_id	string		ID of the user to add.
group_ids	string	repeated	IDs of the groups the user should be added to.

AddUserToGroupsResponse

Represents the result of a user addition to groups.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

CreateGroupRequest

Represents creation of a new group.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
scopes	d1.scopes.Scope	repeated	The scopes the group should be assigned.

CreateGroupResponse

Represents the result of a group creation.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
group_id	string		ID of the new group.

CreateUserRequest

Represents creation of a new user.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
scopes	d1.scopes.Scope	repeated	The scopes the user should be assigned.

CreateUserResponse

Represents the result of a user creation.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
user_id	string		ID of the new user.
password	string		The users password.

LoginUserRequest

Represents the user login.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
user_id	string		ID of the user.
password	string		The users password.

LoginUserResponse

Represents the result of a user login.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
access_token	string		Access token to be used in subsequent requests.
expiry_time	int64		The expiration time of the access token.

RemoveUserFromGroupsRequest

Represents the removal of a user from one or more groups.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
user_id	string		ID of the user to remove.
group_ids	string	repeated	IDs of the groups the user should be removed from.

RemoveUserFromGroupsResponse

Represents the result of a user removal from groups.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

RemoveUserRequest

Represents the removal of a user.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Field	Type	Label	Description
user_id	string		ID of the user to remove.

RemoveUserResponse

Represents the result of a user removal.

NOTE: This is only exposed when the D1 service is configured to use the standalone ID provider.

Authn

Service for user management.

NOTE: This API is only exposed when the D1 service is configured to use the standalone ID provider.

Method Name	Request Type	Response Type	Description
CreateUser	CreateUserRequest	CreateUserResponse	Creates a new user. This call can fail if the auth storage cannot be reached, in which case an error is returned.
LoginUser	LoginUserRequest	LoginUserResponse	Logs in an existing user, returning a User Access Token and an expiry time. This call can fail if the caller provides the wrong credentials or if the auth storage cannot be reached, in which case an error is returned.
RemoveUser	RemoveUserRequest	RemoveUserResponse	Deletes an existing user. This call can fail if the user does not exist, or if the auth storage cannot be reached, in which case an error is returned.
CreateGroup	CreateGroupRequest	CreateGroupResponse	Creates a new group with the requested scopes. The caller is added to the group. This call can fail if the auth storage cannot be reached, in which case an error is returned.
AddUserToGroups	AddUserToGroupsRequest	AddUserToGroupsResponse	Adds a user to one or more groups. This call can fail if the auth storage cannot be reached, in which case an error is returned.
RemoveUserFromGroups	RemoveUserFromGroupsRequest	RemoveUserFromGroupsResponse	Removes a user from one or more groups. This call can fail if the auth storage cannot be reached, in which case an error is returned.

Top

authz.proto

AddPermissionRequest

Represents a request to add permission to an object.

Field	Type	Label	Description
object_id	string		The ID of the object to add the permission to.
group_ids	string	repeated	The IDs of the groups to give access.

AddPermissionResponse

Represents the result of a request to add permission to an object.

CheckPermissionRequest

Represents a request to check whether the user has permission to an object.

Field	Type	Label	Description
object_id	string		The ID of the object to check permission for.

CheckPermissionResponse

Represents the result of a request to check whether a user has permission to an object.

Field	Type	Label	Description
has_permission	bool		Indicates whether the caller has access to the object.

GetPermissionsRequest

Represents a request to get the permissions of an object.

Field	Type	Label	Description
object_id	string		The ID of the object to get the permission list for.

GetPermissionsResponse

Represents the result of a request to get permissions for an object.

Field	Type	Label	Description
group_ids	string	repeated	List of groups with access to the object.

RemovePermissionRequest

Represents a request to remove permission to an object.

Field	Type	Label	Description
object_id	string		The ID of the object to remove the permission for.
group_ids	string	repeated	The IDs of the groups to revoke permission for.

RemovePermissionResponse

Represents the result of a request to remove permission to an object.

Authz

Service for managing authorization rules.

Method Name	Request Type	Response Type	Description
GetPermissions	GetPermissionsRequest	GetPermissionsResponse	Returns a list of groups with access to the specified object. This call can fail if the auth storage cannot be reached, in which case an error is returned. The calling user has to be authenticated and authorized to access the object in order to get the object permissions. Requires the scope GETACCESS.
AddPermission	AddPermissionRequest	AddPermissionResponse	Adds one or more groups to the access list of the specified object. This call can fail if the caller does not have access to the object, if the target group does not exist, or if the auth storage cannot be reached. In these cases, an error is returned. Requires the scope MODIFYACCESS.
RemovePermission	RemovePermissionRequest	RemovePermissionResponse	Removes one or more groups from the access list of the specified object. This call can fail if the caller does not have access to the object or if the auth storage cannot reached. In these cases, an error is returned. Requires the scope MODIFYACCESS.
CheckPermission	CheckPermissionRequest	CheckPermissionResponse	Checks whether the caller has access to the specified object. This call can fail if the auth storage cannot be reached. In this cases, an error is returned. Requires the scope GETACCESS.

Top

index.proto

AddRequest

Represents a request to add keywords/identifier pairs.

Field	Type	Label	Description
keywords	string	repeated	Keywords to be associated with identifier in secure index.
identifier	string		Identifier, e.g. a document ID, to be stored in secure index.

AddResponse

Represents a response to an add request.

DeleteRequest

Represents a request to delete keywords/identifier pairs from secure index.

Field	Type	Label	Description
keywords	string	repeated	Keywords that are associated with identifier in secure index.
identifier	string		Identifier stored in secure index.

DeleteResponse

Represents a response to a delete request.

SearchRequest

Represents a request to search for a keyword in secure index.

Field	Type	Label	Description
keyword	string		Keyword to search for in secure index.

SearchResponse

Represents a response to a search request.

Field	Type	Label	Description
identifiers	string	repeated	Identifiers that contain the keyword in secure index.

Index

Service for using secure index.

Method Name	Request Type	Response Type	Description
Add	AddRequest	AddResponse	Adds keywords/identifier pairs to secure index.
Search	SearchRequest	SearchResponse	Searches in secure index.
Delete	DeleteRequest	DeleteResponse	Deletes keywords/identifier pairs from secure index.

Top

scopes.proto

Scope

Access scopes.

Name	Number	Description
READ	0	Read and decrypt data.
CREATE	1	Store and encrypt data.
GETACCESS	2	Get permissions to an object.
MODIFYACCESS	3	Modify permissions to an object.
UPDATE	4	Modify data.
DELETE	5	Delete data.
INDEX	6	Use secure index for searching in data.

Top

storage.proto

Copyright 2020-2022 CYBERCRYPT

DeleteRequest

Represents a request to delete an object.

Field	Type	Label	Description
object_id	string		The ID of the object to delete.

DeleteResponse

Represents a response to a delete request.

RetrieveRequest

Represents a request to retrieve an object.

Field	Type	Label	Description
object_id	string		The object ID to retrieve.

RetrieveResponse

Represents a response to a retrieve request.

Field	Type	Label	Description
plaintext	bytes		The decrypted data.
associated_data	bytes		Associated data.

StoreRequest

Represents a request to store an object.

Field	Type	Label	Description
plaintext	bytes		Data to encrypt.
associated_data	bytes		Associated data.
group_ids	string	repeated	Optional additional groups to add to the access list.

StoreResponse

Represents a response to a store request.

Field	Type	Label	Description
object_id	string		The object ID to the stored data.

UpdateRequest

Represents a request to update an object.

Field	Type	Label	Description
plaintext	bytes		The data to encrypt.
associated_data	bytes		Associated data.
object_id	string		The ID of the object to update.

UpdateResponse

Represents a response to an update request.

Storage

Service for managing stored objects.

Method Name	Request Type	Response Type	Description
Store	StoreRequest	StoreResponse	Store an object in encrypted form.
Retrieve	RetrieveRequest	RetrieveResponse	Fetches a previously stored object and returns the plaintext content.
Update	UpdateRequest	UpdateResponse	Store an object in encrypted form, replacing the data previously stored.
Delete	DeleteRequest	DeleteResponse	Deletes a previously stored object.

Top

version.proto

VersionRequest

Represents a request to get version information.

VersionResponse

Represents a response to get version information.

Field	Type	Label	Description
commit	string		The Git commit of the running service.
tag	string		The version of the running service.

Version

Service for getting version information.

Method Name	Request Type	Response Type	Description
Version	VersionRequest	VersionResponse	Returns the versions of the currently running service.

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)