CryptoAC as Data Manager
CryptoAC can run as a simple storage service for resources such as documents and files. In this configuration, CryptoAC requires the presence of a Reference Monitor, while the integration with an Access Controller is optional. Moreover, CryptoAC can serve different cores simultaneously and synchronize concurrent requests from users.
Warning
CryptoAC is intended to be used as Data Manager for testing purposes only (at least at the moment), as it offers very limited functionalities and security (e.g., there is not users’ authentication).
To act as a Data Manager, CryptoAC exposes a number of RESTful APIs. More in detail, the administrator can invoke a dedicated API to configure CryptoAC to interact with an Access Controller, if needed. The other APIs follow the Create, Read, Update and Delete (CRUD) paradigm. Users can ask to read a resource by sending a get request to /v1/dm/resources/${core}/${resourceName}, where ${core} is the chosen core type and ${resourceName} is the name (identifier) of the resource; if previously configured, CryptoAC will ask the Access Controller whether the user is authorized to read the resource. If so, CryptoAC will return the (possibly encrypted) requested resource to the user. Users can also ask to add or write over a resource. In both cases, users send a post request to /v1/dm/resources with–as body–the content of the resource. The (new or updated) resource is stored in a temporary bucket until the Reference Monitor confirms the correctness and the compliance of the users’ operation with the policy. Only then, CryptoAC moves the resource to the main bucket, making it available to all (authorized) users.
Expand this to see the OpenAPI documentation on the APIs that CryptoAC exposes when acting as a Data Manager:
openapi: "3.0.0"
info:
version: 0.1.0
title: "CryptoAC - DM"
description: "This is the documentation of the RESTful APIs of [CryptoAC](https://github.com/stfbk/CryptoAC) when configured to act as a Data Manager (DM). Please see the [repository](https://github.com/stfbk/CryptoAC) for information about CryptoAC. Mandatory parameters are rendered as path parameters, while optional parameters are rendered as query parameters."
termsOfService: http://swagger.io/terms/
contact:
name: FBK - Security and Trust
email: sberlato@fbk.eu
url: https://st.fbk.eu/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: http://localhost:8445/v1/dm
paths:
/{CORE}:
post:
summary: "Configure the DM to interact with an AC module for traditional access control enforcement."
description: "If no AC module is used, set the request body to null. This API can be invoked multiple times by the administrator only, with the newer configuration replacing the old one. This API must be invoked at least once before starting to use the DM."
operationId: configureDM
security:
- cookieAuth: []
- basicAuth: []
parameters:
- name: CORE
in: path
description: "The core."
required: true
schema:
type: string
requestBody:
description: "Parameters of the AC module."
content:
multipart/form-data:
schema:
type: array
items:
$ref: '#/components/schemas/ACServiceParameters'
responses:
'200':
description: "Success."
content:
text/plain:
examples:
CODE_000_SUCCESS:
summary: "Success."
value: "CODE_000_SUCCESS"
'422':
description: "Unprocessable Entity."
content:
text/plain:
examples:
CODE_018_INTERFACE_CONFIGURATION_PARAMETERS:
summary: "Supplied wrong configuration parameters (e.g., wrong URL or port)."
value: "CODE_018_INTERFACE_CONFIGURATION_PARAMETERS"
CODE_019_MISSING_PARAMETERS:
summary: "Missing core parameter."
value: "CODE_019_MISSING_PARAMETERS"
'500':
description: "Internal Server Error."
content:
text/plain:
examples:
outcomeCode:
summary: "An outcome code describing the error."
/resources/{CORE}:
post:
summary: "Upload a resource in the DM for the given core."
description: "This API can be invoked by any user."
operationId: addResource
security:
- cookieAuth: []
- basicAuth: []
parameters:
- name: CORE
in: path
description: "The core."
required: true
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
Resource:
type: string
format: binary
description: "The resource to add."
responses:
'200':
description: "Success."
content:
text/plain:
examples:
CODE_000_SUCCESS:
summary: "Success."
value: "CODE_000_SUCCESS"
'409':
description: "Conflict."
content:
text/plain:
examples:
CODE_003_RESOURCE_ALREADY_EXISTS:
summary: "Resource already exists."
value: "CODE_003_RESOURCE_ALREADY_EXISTS"
'422':
description: "Unprocessable Entity."
content:
text/plain:
examples:
CODE_019_MISSING_PARAMETERS:
summary: "Missing core, resource or resource name parameters."
value: "CODE_019_MISSING_PARAMETERS"
'500':
description: "Internal Server Error."
content:
text/plain:
examples:
outcomeCode:
summary: "An outcome code describing the error."
'503':
description: "Service Unavailable."
content:
text/plain:
examples:
CODE_075_DM_CONFIGURATION:
summary: "DM was not configured."
value: "CODE_075_DM_CONFIGURATION"
/resources/{CORE}/{Resource_Name}:
get:
summary: "Download the resource from the DM for the given core."
description: "This API can be invoked by any user."
operationId: getResource
security:
- cookieAuth: []
- basicAuth: []
parameters:
- name: CORE
in: path
description: "The core."
required: true
schema:
type: string
- name: Resource_Name
in: path
description: "The name of the resource."
required: true
schema:
type: string
- name: Username
in: query
description: "The name of the user requesting the resource."
required: true
schema:
type: string
responses:
'200':
description: ok
content:
application/octet-stream:
schema:
type: string
format: binary
headers:
Content-Disposition:
schema:
type: string
description: Used only with `application/octet-stream` responses
example: attachment; filename="name.pdf"
'404':
description: "Not found."
content:
text/plain:
examples:
CODE_006_RESOURCE_NOT_FOUND:
summary: "Resource not found. This code is returned both when the resource does not actually exist and when the resource exists but the user does not have access to it."
value: "CODE_006_RESOURCE_NOT_FOUND"
'422':
description: "Unprocessable Entity."
content:
text/plain:
examples:
CODE_019_MISSING_PARAMETERS:
summary: "Missing core, resource or user name parameters."
value: "CODE_019_MISSING_PARAMETERS"
'500':
description: "Internal Server Error."
content:
text/plain:
examples:
outcomeCode:
summary: "An outcome code describing the error."
'503':
description: "Service Unavailable."
content:
text/plain:
examples:
CODE_075_DM_CONFIGURATION:
summary: "DM was not configured."
value: "CODE_075_DM_CONFIGURATION"
put:
summary: "Confirm the add or write operation forof the resource for the given core."
description: "If no AC module is present, this API can be invoked by the administrator and the RM only. Otherwise, this API can be invoked by any user."
operationId: moveResource
security:
- cookieAuth: []
- basicAuth: []
parameters:
- name: CORE
in: path
description: "The core."
required: true
schema:
type: string
- name: Resource_Name
in: path
description: "The name of the resource."
required: true
schema:
type: string
- name: Username
in: query
description: "The name of the user requesting to write over the resource."
required: true
schema:
type: string
responses:
'200':
description: "Success."
content:
text/plain:
examples:
CODE_000_SUCCESS:
summary: "Success."
value: "CODE_000_SUCCESS"
'403':
description: "Forbidden."
content:
text/plain:
examples:
CODE_037_FORBIDDEN:
summary: "No AC module is present but the API was invoked by a non-admin user."
value: "CODE_037_FORBIDDEN"
'404':
description: "Not found."
content:
text/plain:
examples:
CODE_006_RESOURCE_NOT_FOUND:
summary: "Resource not found. This code is returned both when the resource does not actually exist and when the resource exists but the user does not have access to it."
value: "CODE_006_RESOURCE_NOT_FOUND"
'422':
description: "Unprocessable Entity."
content:
text/plain:
examples:
CODE_019_MISSING_PARAMETERS:
summary: "Missing core, resource or user name parameters."
value: "CODE_019_MISSING_PARAMETERS"
'500':
description: "Internal Server Error."
content:
text/plain:
examples:
CODE_025_RESOURCE_WRITE:
summary: "File system error while writing the resource."
value: "CODE_025_RESOURCE_WRITE"
CODE_058_INCONSISTENT_STATUS_DELETE_TEMPORARY_RESOURCE_IN_DM:
summary: "File system error while deleting the old resource."
value: "CODE_058_INCONSISTENT_STATUS_DELETE_TEMPORARY_RESOURCE_IN_DM"
outcomeCode:
summary: "An outcome code describing the error."
'503':
description: "Service Unavailable."
content:
text/plain:
examples:
CODE_075_DM_CONFIGURATION:
summary: "DM was not configured."
value: "CODE_075_DM_CONFIGURATION"
delete:
summary: "Delete the resource from the DM for the given core."
description: "This API can be invoked by the administrator only."
operationId: deleteResource
security:
- cookieAuth: []
- basicAuth: []
parameters:
- name: CORE
in: path
description: "The core."
required: true
schema:
type: string
- name: Resource_Name
in: path
description: "The name of the resource."
required: true
schema:
type: string
- name: Username
in: query
description: "The name of the user requesting to delete the resource."
required: true
schema:
type: string
responses:
'200':
description: "Success."
content:
text/plain:
examples:
CODE_000_SUCCESS:
summary: "Success."
value: "CODE_000_SUCCESS"
'403':
description: "Forbidden."
content:
text/plain:
examples:
CODE_037_FORBIDDEN:
summary: "The API was invoked by a non-admin user."
value: "CODE_037_FORBIDDEN"
'404':
description: "Not found."
content:
text/plain:
examples:
CODE_006_RESOURCE_NOT_FOUND:
summary: "Resource not found. This code is returned both when the resource does not actually exist and when the resource exists but the user does not have access to it."
value: "CODE_006_RESOURCE_NOT_FOUND"
'422':
description: "Unprocessable Entity."
content:
text/plain:
examples:
CODE_019_MISSING_PARAMETERS:
summary: "Missing core, resource or user name parameters."
value: "CODE_019_MISSING_PARAMETERS"
'500':
description: "Internal Server Error."
content:
text/plain:
examples:
CODE_024_RESOURCE_DELETE:
summary: "File system error while deleting the resource."
value: "CODE_024_RESOURCE_DELETE"
outcomeCode:
summary: "An outcome code describing the error."
'503':
description: "Service Unavailable."
content:
text/plain:
examples:
CODE_075_DM_CONFIGURATION:
summary: "DM was not configured."
value: "CODE_075_DM_CONFIGURATION"
/temporaryResources/{CORE}/{Resource_Name}:
delete:
summary: "Delete the temporary resource from the DM for the given core."
description: "This API can be invoked by the administrator only."
operationId: deleteTemporaryResource
security:
- cookieAuth: []
- basicAuth: []
parameters:
- name: CORE
in: path
description: "The core."
required: true
schema:
type: string
- name: Resource_Name
in: path
description: "The name of the resource."
required: true
schema:
type: string
- name: Username
in: query
description: "The name of the user requesting to delete the temporary resource."
required: true
schema:
type: string
responses:
'200':
description: "Success."
content:
text/plain:
examples:
CODE_000_SUCCESS:
summary: "Success."
value: "CODE_000_SUCCESS"
'403':
description: "Forbidden."
content:
text/plain:
examples:
CODE_037_FORBIDDEN:
summary: "The API was invoked by a non-admin user."
value: "CODE_037_FORBIDDEN"
'404':
description: "Not found."
content:
text/plain:
examples:
CODE_006_RESOURCE_NOT_FOUND:
summary: "Resource not found. This code is returned both when the resource does not actually exist and when the resource exists but the user does not have access to it."
value: "CODE_006_RESOURCE_NOT_FOUND"
'422':
description: "Unprocessable Entity."
content:
text/plain:
examples:
CODE_019_MISSING_PARAMETERS:
summary: "Missing core, resource or user name parameters."
value: "CODE_019_MISSING_PARAMETERS"
'500':
description: "Internal Server Error."
content:
text/plain:
examples:
CODE_024_RESOURCE_DELETE:
summary: "File system error while deleting the resource."
value: "CODE_024_RESOURCE_DELETE"
outcomeCode:
summary: "An outcome code describing the error."
'503':
description: "Service Unavailable."
content:
text/plain:
examples:
CODE_075_DM_CONFIGURATION:
summary: "DM was not configured."
value: "CODE_075_DM_CONFIGURATION"
components:
securitySchemes:
cookieAuth:
type: apiKey
in: cookie
name: JSESSIONID
basicAuth:
type: http
scheme: basic
schemas:
ACServiceParameters:
description: Parameters to configure an Access Controller module. See the Core Profile section of the documentation for more details.
type: "object"
CryptoAC as Data Manager Configuration
To interact with an instance of CryptoAC configured as a Data Manager, CryptoAC needs to know the endpoint (i.e., the URL and the port) on which the instance is listening to connections and the client’s username and password; see the Core Profiles section for more details. Whenever the administrator adds a user to the policy, CryptoAC also creates the user’s account in the Data Manager and generates the user’s password. Intuitively, the Data Manager should have already been configured with an account for the administrator. Then, at start-up, if requested, CryptoAC configures the instance acting as a Data Manager with the parameters required to interact with an Access Controller.