openapi: 3.0.3 info: title: >- SafeStorage version: v1.0 license: name: PN software license url: 'https://www.pn.pagopa.it/LICENSE' description: >- __SafeStorage__: memorizza e __archivia a fini legali file non modificabili__. Opzionalmente appone firma digitale e marcatura temporale. #### Elenco casi d'uso da soddisfare: - Upload degli allegati di una notifica, già firmati dalle PA, da mantenere per 120gg.
- Upload, firma digitale e marcatura temporale degli atti opponibili a terzi. Conservare 10 anni.
- Upload Avvisi di Avvenuta Ricezione.
- Upload dei documenti digitali generati da pn-external-channels durante la consegna di messaggi digitali e copie conformi dei documenti generati durante la consegna di corrispondenza cartacea. Questi documenti vanno conservati 10 anni
- Download dei file e verifica dei loro checksum.
- In caso di contenzioso bisogna allungare il periodo di retention per file specifici. #### Requisiti non funzionali: - I file contenuti nel _SafeStorage_ devono essere "reccuperabili" in caso di disastro di una regione.
- I file possono essere di dimensioni fino a 1GB, solitamente nell'ordine di 1MB ad eccezione dei documenti allegati alle notifiche che spesso arrivano ai 50MB.
- SafeStorage deve garantire la validità della marcatura temporale nel tempo.
#### Parametri di runtime: - pst: il tempo (secondi o minuti) in cui un presigned URL rimane valido. - stayHotTime: quanto tempo un file che era stato archiviato e poi richiamato rimane "hot" prima di essere nuovamente archiviato. #### Operazioni da invocare per l'archiviazione di un nuovo file. 1. Invocare POST al path '/safe-storage/v1/files' (operation id: createFile )
2. Invocare PUT sul presigned URL ottenuto (operation id: uploadFileContent )
3. Quando il file è stato caricato e firmato/marcato verrà inserito un messaggio in una coda SQS specifica per il client che ha richiesto l'operazione. #### Operazioni da invocare per la lettura di un file esistente. 1. Invocare GET al path '/safe-storage/v1/files/{fileKey}' (operation id: getFile )
2. Il file può essere hot (pronto al download) o cold (minuti o ore per il recupero del file)
3. 1. Se il fle è _hot_ la risposta contiene un url di download da usare entro ```pst``` (tempo validità presigned url); `pst` è parametro di installazione di SafeStorage. 2. Se il file è _cold_ la risposta contiene un indicazione del tempo necessario a renderlo _hot_.
Solo in questo caso, quando il file sarà pronto, verrà inserito un messaggio in una coda SQS specifica per il client che ha richiesto l'operazione. Tale messaggio conterrà l'URL di download. 4. L'url di download può essere utilizzato, entro la sua scadenza, per recuperare il contenuto del file. servers: - url: >- https://api.pn.pagopa.it description: Server url tags: - name: cfg description: Configurazioni - name: fileUpload description: Caricamento file - name: fileDownload description: Lettura file - name: fileMetadataUpdate description: Aggiornamento metadati file paths: ################################################################################################ ### CONFIGURAZIONI ### ################################################################################################ '/safe-storage/v1/configurations/documents-types': get: operationId: getDocumentsConfigs summary: Elenca tipologie di documenti e caratteristiche di storage. description: >- #### Le tipologie di documenti sono un elenco fisso che prevede: - _PN_NOTIFICATION_ATTACHMENTS_: gli allegati di una notifica siano essi documenti, F24 o bollettini pagoPA. Hanno due stati: _PRELOADED_ che indica un documento appena caricato ma non ancora allegato a nessuna notifica; _ATTACHED_ una volta che un documento viene allegato a una notifica.
- _PN_AAR_: Avvisi di Avvenuta Ricezione generati da pn-delivery-push e inviati con pn-external-channels.
- _PN_LEGAL_FACTS_: atti opponibili a terzi generati da pn-delivery-push; vanno firmati digitalmente e sottoposti a marcatura temporale.
- _PN_EXTERNAL_LEGAL_FACTS_: atti opponibili a terzi generati dai sistemi di messaggistica esterni a Piattaforma Notifiche. Sono firmati e marcati esternamente. #### Caratteristiche per tipologia di documento: - _statuses_: elenco degli stati assumibili dal file
- _informationClassification_: C o HC. Se è HC il file deve essere criptato.
- _digitalSignature_: indica se il file va firmato digitalemnte
- _timestamped_: _NONE_ o _STANDARD_. Indica che tipo di marcatura temporale è necessario.
- _checksum_: _MD5_ o _SHA256_. Per l'implementazione si può sfruttare la feature https://aws.amazon.com/it/blogs/aws/new-additional-checksum-algorithms-for-amazon-s3/ di S3. #### Caratteristiche di storage (variano per tipo e stato di un file): - _retentionPeriod_: quanto a lungo il file deve essere mantenuto.
- _hotPeriod_: per quanto tempo il file rimane in S3 standard o IA. Dopo tale periodo può essere archiviato in S3 glacier.
tags: - cfg responses: '404': description: Not configured '200': description: OK content: application/json: schema: $ref: '#/components/schemas/DocumentTypesConfigurations' example: documentsTypes: - name: PN_NOTIFICATION_ATTACHMENTS informationClassification: 'HC' initialStatus: 'PRELOADED' digitalSignature: false timestamped: NONE checksum: SHA256 statuses: PRELOADED: storage: PN_TEMPORARY_DOCUMENT allowedStatusTransitions: - ATTACHED ATTACHED: storage: PN_NOTIFIED_DOCUMENTS allowedStatusTransitions: [] - name: PN_AAR informationClassification: 'HC' initialStatus: 'SAVED' digitalSignature: false timestamped: NONE checksum: MD5 statuses: SAVED: storage: PN_AAR allowedStatusTransitions: [] - name: PN_LEGAL_FACTS informationClassification: 'HC' allowedInitialStatus: [ 'SAVED' ] digitalSignature: true timestamped: 'STANDARD' checksum: MD5 statuses: SAVED: storage: PN_LEGAL_FACTS allowedStatusTransitions: [] - name: PN_EXTERNAL_LEGAL_FACTS informationClassification: 'HC' initialStatus: 'SAVED' digitalSignature: false timestamped: NONE checksum: MD5 statuses: SAVED: storage: PN_LEGAL_FACTS allowedStatusTransitions: [] storageConfigurations: - name: PN_TEMPORARY_DOCUMENT retentionPeriod: '1d' hotPeriod: '1d' - name: PN_NOTIFIED_DOCUMENTS retentionPeriod: '120d' hotPeriod: '120d' - name: PN_LEGAL_FACTS retentionPeriod: '10y' hotPeriod: '120d' - name: PN_AAR retentionPeriod: '10y' hotPeriod: '10d' '/safe-storage/v1/configurations/clients/{clientId}': get: operationId: getCurrentClientConfig summary: Dettagli di configurazione di un client description: >- Ogni microservizio che vuole utilizzare _SafeStorage_ deve essere censito, avere almeno una api-key assegnata, e avere alcune configurazioni:
- _name_: il nome del sistema upstream (client).
- _canCreate_: tipi di documento che il client può caricare.
- _canRead_: tipi di documento che il client può leggere.
- _signatureInfo_: informazioni necessarie per firmare digitalmente, per conto
del client, i file caricati.
- _destination_: informazioni necessarie a notificare eventi al client. tags: - cfg parameters: - $ref: '#/components/parameters/clientIdPath' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UserConfiguration' examples: pnDelivery: summary: 'pn-delivery' value: name: 'pn-delivery' canCreate: [ 'PN_NOTIFICATION_ATTACHMENTS' ] canRead: [ 'PN_NOTIFICATION_ATTACHMENTS' ] signatureInfo: {} destination: sqsUrl: https://sqs.eu-central-1.amazonaws.com/558518206506/pn-delivery-document-saved pnDeliveryPush: summary: 'pn-delivery-push' value: name: 'pn-delivery-push' canCreate: [ 'PN_AAR', 'PN_LEGAL_FACTS' ] canRead: [ 'PN_AAR', 'PN_LEGAL_FACTS', 'PN_EXTERNAL_LEGAL_FACTS' ] signatureInfo: {} destination: sqsUrl: https://sqs.eu-central-1.amazonaws.com/558518206506/pn-delivery-push-document-saved pnExternalChannels: summary: 'pn-external-channels' value: name: 'pn-external-channels' canCreate: [ 'PN_EXTERNAL_LEGAL_FACTS' ] canRead: [ 'PN_AAR', 'PN_EXTERNAL_LEGAL_FACTS' ] signatureInfo: {} destination: sqsUrl: https://sqs.eu-central-1.amazonaws.com/558518206506/pn-external-channels-document-saved '404': description: Non trovato. Restituito se il parametro clientId è diverso dal client autenticato ################################################################################################ ### CARICAMENTO FILE ### ################################################################################################ '/safe-storage/v1/files': post: operationId: createFile tags: - fileUpload summary: Prenota caricamento file description: >- Questa operazione chiede la generazione di un URL per caricare un nuovo file. Dovrà essere seguita da una chiamata all'URL generato che servirà a caricare l'effettivo contenuto del file. Il tempo massimo che può intercorrere tra le due invocazioni è ```pst```. parameters: - $ref: '#/components/parameters/clientIdHeader' - name: x-checksum in: header schema: type: string - name: x-checksum-value in: header schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/FileCreationRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FileCreationResponse' '404': description: Non trovato. Restituito se il parametro clientId è diverso dal client autenticato '/sage-storage/v1/upload-with-presigned-url': put: operationId: uploadFileContent tags: - fileUpload summary: Carica contenuto file description: >- #### UTILIZZO DEL URL DI UPLOAD, NON VA IMPLEMENTATA COME API. SERVE PER DOCUMENTAZIONE PUT o POST necessaria a caricare il contentuto del file tramite presigned URL. Il presigned url deve essere utilizzabile una volta sola.
Al termine di questa invocazione _SafeStorage_ avvierà, se necessario, i processi di firma digitale e marcatura temporale. In ogni caso, quando il file e i suoi metadati saranno completi e disponibili sullo storage, verrà notificato un evento al client che ha prenotato il presigned URL utilizzato. parameters: - name: Content-Type in: header schema: type: string - name: x-amz-meta-secret in: header schema: type: string description: >- __discutibile__ Token aggiuntivo per far si che sia necessario intercettare anche gli header e non solo l'URL. requestBody: content: '*/*': schema: type: string format: binary responses: '200': description: OK headers: x-amz-version-id: schema: type: string '403': description: presigned URL scaduto callbacks: putIntoSqs: 'configuredSqsPath': put: summary: Send 'file ready' event to SQS requestBody: content: application/json: schema: $ref: '#/components/schemas/FileCreatedDto' responses: '204': description: OK '404': description: SQS queue not found ################################################################################################ ### DOWNLOAD FILE ### ################################################################################################ '/safe-storage/v1/files/{fileKey}': parameters: - $ref: '#/components/parameters/fileKey' - $ref: '#/components/parameters/clientIdHeader' get: operationId: getFile tags: - fileDownload summary: ottieni metadati e contenuto di un file. description: >- Con questa API si ottengono i metadati riguardanti un file caricato in precedenza.
E' anche possibile ottenere le informazioni necessarie al download del contenuto del file; tali informazioni sono contenute nel campo _download_.
- _url_: se il contenuto del file è immediatamente disponibile questo campo viene valorizzato con un URL da invocare in GET per ottenere il contenuto del file.
- _retryAfter_: valorizzato se il contenuto del file è stato archiviato in glacier. Indica una stima del tempo necessario per recuperare il file.
Se il file non è pronto al momento dell'invocazione il campo _download.url_ della risposta verrà valorizzato ```null```; in un secondo momento, quando il contenuto del file sarà pronto verrà comunicato un evento al client che ha invocato la chiamata. Molteplici invocazioni di questa API generano un solo evento per client.
Il file rimane hot per ```stayHotTime````. parameters: - name: metadataOnly in: query description: >- se assente o valorizzato _false_ allora la risposta conterrà il campo _download_. required: false schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/FileDownloadResponse' examples: hotFile: summary: File pronto per il download value: key: 'random/path/of/the/file' versionId: '3Z9SdhZ50PBeIj617KEMrztNKDMJj8FZ' contentType: 'application/pdf' contentLength: 30438 checksum: '91375e9e5a9510087606894437a6a382fa5bc74950f932e2b85a788303cf5ba0' retentionUntil: '2032-04-12T12:32:04.000Z' documentType: PN_LEGALFACT documentStatus: SAVED download: url: 'https://presignedurldemo.s3.eu-west-2.amazonaws.com/...' coldFile: summary: File su glacier. description: Il file è stato archiviato. Verrà recuperato in 24 ore. value: key: 'random/path/of/the/file' versionId: '3Z9SdhZ50PBeIj617KEMrztNKDMJj8FZ' contentType: 'application/pdf' contentLength: 30438 checksum: '91375e9e5a9510087606894437a6a382fa5bc74950f932e2b85a788303cf5ba0' retentionUntil: '2032-04-12T12:32:04.000Z' documentType: PN_LEGALFACT documentStatus: SAVED download: retryAfter: 86400 '404': description: >- Non trovato. Restituito se:
- il parametro clientId è diverso dal client autenticato;
- se il file identificato da fileKey non è ancora stato salvato;
callbacks: putIntoSqs: 'configuredSqsPath': put: summary: Send 'file ready' event to SQS description: L'evento viene accodato solo se il file non è disponibile immediatamente. requestBody: content: application/json: schema: $ref: '#/components/schemas/FileDownloadResponse' responses: '204': description: OK '404': description: SQS queue not found ################################################################################################ ### AGGIORNA METADATI FILE ### ################################################################################################ post: operationId: updateFileMetadata tags: - fileMetadataUpdate summary: Modifica i metadati di un file. description: >- __Il contenuto del file è immodificabile__.
Solo alcuni metadati possono essere aggiornati. - _lo stato di un file_; modificato quando un documento precaricato viene allegato a una notifica. In tale situazione bisogna cambiare la "lifecycle policy" e il "retention period" associato a quel file.
- il _retentionUntil_ ovvero la data di scadenza del file. Questo metadato viene aggiornato in caso che il file serva come prova in un contenzioso legale. In tal caso il "retentionPeriod" va esteso per tutta la durata del dibattimento.
requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateFileMetadataRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/UpdateFileMetadataResponse' '404': description: >- Non trovato. Restituito se:
- il parametro clientId è diverso dal client autenticato;
- se il file identificato da fileKey non è ancora stato salvato;
components: parameters: clientIdPath: name: clientId description: Identificativo del sistema client in: path required: true schema: type: string example: pn-delivery-push clientIdHeader: name: x-pagopa-safestorage-cx-id description: Identificativo del sistema client in: header required: true schema: type: string example: pn-delivery-push fileKey: name: fileKey description: La chiave definita per il file al momento della richiesta di prenotazione di un upload in: path required: true schema: type: string example: '8F7E/9A3B/1234/AB87' schemas: FileCreationRequest: description: Richiesta di autorizzazione a caricare un nuovo file type: object required: - contentType - documentType - status properties: contentType: type: string description: Il MIME format del contenuto del file che si intende caricare example: 'application/pdf' documentType: type: string description: >- Il tipo di documento da caricare; definisce diritti di accesso e tempo di permanenza del file all'interno di _SafeStorage_ example: 'PN_NOTIFICATION_ATTACHMENTS' status: type: string description: >- lo stato del documento, ne definisce il tempo di permanenza all'interno di _SafeStorage_. example: PRELOADED FileCreationResponse: description: Informazioni necessarie a caricare il contenuto di un file type: object required: - uploadMethod - uploadUrl - secret - key properties: uploadMethod: type: string enum: [ 'PUT', 'POST' ] description: >- Indica se per l'upload del contenuto file bisogna utilizzare il metodo PUT o POST uploadUrl: type: string description: >- URL a cui effettuare l'upload del contenuto del documento. example: 'https://preloadpn.aws.amazon.......' secret: type: string description: >- __discutibile__ Token aggiuntivo per far si che sia necessario intercettare anche gli header e non solo l'URL di upload del contenuto del documento. example: AZ23RF12 key: type: string description: >- la chiave restituita deve essere globalmente unica per installazione di SafeStorage e persistente attraverso i processi di disaster recovery. example: '8F7E/9A3B/1234/AB87' FileDownloadResponse: description: Informazioni necessarie al download del contenuto di un file allOf: - $ref: '#/components/schemas/FileCreatedDto' - type: object properties: download: $ref: '#/components/schemas/FileDownloadInfo' FileCreatedDto: description: >- Evento generato quando il contenuto di un file è stato caricato, elaborato da _SafeStorage_, ed è pronto all'uso. type: object required: - key - versionId - contentType - contentLength - checksum - documentType - documentStatus - retentionUntil properties: key: type: string description: la chiave da utilizzare per il recupero del file example: '8F7E/9A3B/1234/AB87' versionId: type: string description: __discutibile__. La versione del file su S3 example: '3Z9SdhZ50PBeIj617KEMrztNKDMJj8FZ' documentType: type: string description: Il tipo del documento example: PN_NOTIFICATION_ATTACHMENTS documentStatus: type: string description: Lo stato del documento example: ATTACHED contentType: type: string example: 'application/pdf' contentLength: type: number example: 54092 description: dmensione, in byte, del contenuto. checksum: type: string description: >- SHA256 o MD5 del contenuto del file. Il tipo di checksum cambia a seconda del documentType. retentionUntil: type: string format: date-time description: >- data e ora fino a cui il documento sarà garantito all'interno di _SafeStorage_.
Può essere ritardata nel tempo, mai anticipata. FileDownloadInfo: type: object properties: url: type: string description: >- URL preautorizzato a cui effettuare una richiesta GET per ottenere il contenuto del documento. Presente solo se il documento è pronto per il download. retryAfter: type: number description: >- Stima del numero di secondi da aspettare prima che il contenuto del documento sia scaricabile. UpdateFileMetadataRequest: type: object properties: status: type: string description: Lo stato del documento example: ATTACHED retentionUntil: type: string format: date-time description: >- data e ora fino a cui il documento sarà garantito all'interno di _SafeStorage_.
Può essere ritardata nel tempo, mai anticipata. UpdateFileMetadataResponse: $ref: '#/components/schemas/OperationResultCodeResponse' UserConfiguration: type: object required: - name - canCreate - canRead - destination properties: name: type: string description: identificativo del sistema client example: pn-delivery-push canCreate: type: array items: type: string description: Elenco dei tipi di documenti che il client è autorizzato a creare. canRead: type: array items: type: string description: Elenco dei tipi di documenti che il client è autorizzato a creare. signatureInfo: type: object description: __DA DEFINIRE__ configurazioni necessarie per la firma digitale destination: type: object description: Informazioni per contattare in modalità push i sistemi client. properties: sqsUrl: type: string description: URL della coda SQS a cui contattare il client DocumentTypesConfigurations: type: object description: Configurazione delle tipologie di documenti required: - documentsTypes - storageConfigurations properties: documentsTypes: type: array items: $ref: '#/components/schemas/DocumentTypeConfiguration' description: Elenco tipologie di documenti storageConfigurations: type: array items: $ref: '#/components/schemas/StorageConfiguration' description: Configurazione Retention Period e tipologie di storage per ogni documento. TimePeriod: type: string pattern: '([0-9]+y)?([0-9]+d)?' minLength: 1 example: '1y10d' description: Numero di anni e/o di giorni StorageConfiguration: type: object required: - name - retentionPeriod - hotPeriod properties: name: type: string retentionPeriod: description: >- Quanto tempo _SafeStorage_ deve mantenere il documento, è possibile allungare tale periodo, mai diminuirlo. $ref: '#/components/schemas/TimePeriod' hotPeriod: description: Per quanto tempo mantenere il file pronto al download. $ref: '#/components/schemas/TimePeriod' DocumentTypeConfiguration: type: object properties: name: type: string description: nome del tipo di documento informationClassification: $ref: '#/components/schemas/ConfidentialityLevel' digitalSignature: type: boolean timestamped: type: string enum: [ 'NONE', 'STANDARD' ] checksum: description: >- codice di verifica del corretto caricamento del file https://aws.amazon.com/it/blogs/aws/new-additional-checksum-algorithms-for-amazon-s3/ type: string enum: [ 'MD5', 'SHA256'] statuses: description: >- Elenco degli stati che un documento può assumere. Usato solo per gli allegati della notifica. type: object additionalProperties: type: object properties: storage: type: string description: >- La definizione delle caratteristiche di storage per lo specifico stato del docuemtno. allowedStatusTransitions: description: Transizioni possibili dallo stato corrente type: array items: type: string initialStatus: description: Stato iniziale in cui viene creato un documento. type: string ConfidentialityLevel: type: string enum: ['C', 'HC'] description: > * `C` - Confidential * `HC`- Highly Confidential See [information classification](https://pagopa.atlassian.net/wiki/spaces/EN/pages/357204284/Data+Classification+Handling#Classificazione) OperationResultCodeResponse: required: - resultCode - resultDescription - clientResponseTimeStamp type: object properties: resultCode: type: string example: '400.00' description: >- Codice a 5 cifre separate da punto che indica l’esito della richiesta. LE prime tre sono ripetizione del codice HTTP
Per convenzione, la sequenza 2000 indicherà OK.
- '200.00' OK
- '400.01' Errore di validazione sintattica del messaggio
- '400.02' Errore di validazione regole semantiche
- '404.00' requestId mai ricevuto
- '409.00' requestId già utilizzato
- '500.xy' Errori interni al server
- .... Altri errori previsti dalla specifica implementazione
resultDescription: type: string example: 'Request validation errors' description: >- Descrizione dell’Esito dell’operazione, sempre valorizzato, anche in caso di esito positivo.
In caso di errore dovrà contenere info utili al chiamante per indirizzare le azioni correttive necessarie.
In nessun caso conterrà dettagli tecnici e/o stack trace.
errorList: type: array items: type: string example: 'retentionDate cannot be anticipated' description: >- Elenco degli errori di validazione, se presenti. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key security: - ApiKeyAuth: [] # use the same name as under securitySchemes # CRITTIGRAFIAAAA Transparent encription con CloudHSF va bene ? # Accertamenti su marcatura temporale