Define Key service interface with OpenAPI

[juhtornr]

No description provided.

[blankdots]

OpenPGP keyserver draft implementation protocol https://tools.ietf.org/html/draft-shaw-openpgp-hkp-00 implemented by: http://pgp.key-server.io/ or http://pgp.mit.edu/ and others

Draft:

GET endpoints:

/filekey/{file_id}
NOTE: EGAF ids or namespace id
NOTE: one key per file ingestion

/user/{user_id}/key/public

/active/{key_type}/{key_id}
/retrieve/{key_type}/{key_id}/private

POST: 

/user/{user_id}/key/public
Note: secure endpoint with proper authentication
Note: if a user resubmits a key we will deactivate the old on in the code and store it somewhere

[juhtornr]

The /active part seems redundant. How about /retrieve/{key_type}/{key_id}/public
or even /key/{key_type}/{key_id} followed by /public or /private

[omllobet]

ours probably is /keys/{key_id}

[omllobet]

The generic document that we use for rest api guidelines is https://docs.google.com/document/d/1mukWvbZ3uhrLg960NU44n_RyGnmKG8f4skVWn2xkUAM/

Also it could be interesting to be able to retrieve the keys of a user. For example when we generate a download box for a user, it would be needed to know which key has to be used for that user, and maybe a type param if the user can have multiple keys.

/users/{user_id}/keys?type=xxx

[omllobet]

So here is the rest interface

Getting the AES key for a specific file
/keys/filekeys/{fileId}
return String

/keys/retrieve/{keyId}/public
returns PGPPublicKey

/keys/retrieve/{keyId}/public/{keyType}
return String

Getting a Private Key
/keys/retrieve/{keyId}/private/object
return PGPPrivateKey

/keys/retrieve/{keyId}/private/path
return KeyPath

/keys/retrieve/{keyId}/private/key
returns string

Return all current Key IDs
/keys/retrieve/{keyType}/ids
Set

---

I think that the retrieve word is an extra as the endpoints use the get http verb.
Then it seems that there is some specific pgp functionality as some enpoints return PGPPublicKey and PGPPrivateKey, that may be under a /pgp/ endpoint better

I also found there is an inconsistency in the filekeys endpoint. To me that endpoint would be soemthing like /files/{fileId}/keys and for a user key would be /users/{userId}/keys And if you already know the keyId for a file, It seems there is no way to obtain it right, or one must use /keys/retrieve/{keyId}/public/{keyType} ? but if it's a symmetric key it does not make sense right? For getting a key, the endpoint would be just keys/{keyId}

About the keyId is not clear if you are always referring to the keyId assigned by PGP or to an internal keyId, like how a keyid would be generated for a symmetric key?

So what do you think about my comments?

Thanks

[juhtornr]

I created OpenAPI specification based on current implementation:

https://app.swaggerhub.com/apis/ELIXIR-Finland/Local-EGA-Key-service/1.0.0

It has all the endpoints but not the responses. Let's try to agree on endpoints before moving to the responses.

[silverdaz]

Good job.
The word retrieve should be removed from the endpoints, if you want to make it look more REST-like

[juhtornr]

Ok I think that the retrieve keyword should be removed and the implementation should be tuned to match new specification. Also that OpenAPI should be stored in this repository.