#%RAML 1.0
title: keyfender API
version: v0
description: All <a href="https://tools.ietf.org/html/rfc4648#section-4">base64url</a> encoded values are Big Endian.
baseUri: https://{hostName}:{hostPort}/api/{version}
baseUriParameters:
  hostName:
    description: Host name or host IP address
  hostPort:
    description: Port of the host
protocols: HTTPS # TODO. Currently HTTP only.
mediaType: application/json
securitySchemes:
  basic:
    description: This API supports Basic Authentication.
    type: Basic Authentication
# Maybe describe which user role to use for each operation. See: http://forums.raml.org/t/allow-get-endpoint-to-be-both-secure-and-un-secure/1134/4

types:
  PrivateRsaKey:
    type: object
    properties:
      primeP: string
      primeQ: string
      publicExponent: string
    additionalProperties: false
  PublicRsaKey:
    type: object
    properties:
      modulus: string
      publicExponent: string
    additionalProperties: false
  PublicKeyEnvelope:
    type: object
    properties:
      purpose: string
      algorithm: string
      publicKey: PublicRsaKey
  KeyImport:
    type: object
    properties:
      purpose: string
      algorithm: string
      privateKey: PrivateRsaKey
    additionalProperties: false
  KeyGeneration:
    type: object
    properties:
      purpose: string
      algorithm: string
      length: integer
    additionalProperties: false
  KeyImportWithId:
    type: object
    properties:
      purpose: string
      algorithm: string
      privateKey: PrivateRsaKey
      id: string
    additionalProperties: false
  KeyGenerationWithId:
    type: object
    properties:
      purpose: string
      algorithm: string
      length: integer
      id: string
    additionalProperties: false
  KeyList:
    type: array
    items:
      type: object
      properties:
        location: string
      additionalProperties: false
  KeyLocation:
    type: object
    properties:
      location: string
  SystemInformation:
    type: object
    properties:
      vendor: string
      product: string
      version: string
    additionalProperties: false
  PasswordChange:
    type: object
    properties:
      newPassword: string
    additionalProperties: false

/keys:
  description: The keys being stored in the keyfender.
  post:
    description: Import or generate a key pair in(to) keyfender at a specified location.
    securedBy: basic # Administrator
    body:
      application/json:
        type: KeyImportWithId | KeyGenerationWithId
        examples:
          KeyImportWithId:
            purpose: "signing"
            algorithm: "RSA"
            privateKey:
              primeP: "frtz7u89gft89uz"
              primeQ: "FhJQl11CiY0ifRHXeAqFh4rdSl6"
              publicExponent: "w367rg90jhj0asdf98gz"
            id: "myKey1"
          KeyGenerationWithId:
            purpose: "signing"
            algorithm: "RSA"
            length: 2048
            id: "myKey1"
    responses:
      200:
        body:
          application/json:
            type: KeyLocation
            example:
              location: "/api/{version}/myKey1"
      404:
      500:
  get:
    description: Retrieve a list of all existing key locations.
    securedBy: basic # User
    responses:
      200:
        body:
          application/json:
            type: KeyList
            example: [location: "/api/v1/gz78ijhbhuij", location: "/api/v1/mykeyId"]
      401: # unauthorized

  /{keyId}:
    delete:
      description: Deletes the specified key pair.
      securedBy: basic # Administrator
      responses:
        200:
        404:
        500:
    put:
      description: Replaces an existing key pair by importing or generating a new key pair.
      securedBy: basic # Administrator
      body:
        application/json:
          type: KeyImport | KeyGeneration
          examples:
            KeyImport:
              purpose: "signing"
              algorithm: "RSA"
              privateKey:
                primeP: "frtz7u89gft89uz"
                primeQ: "FhJQl11CiY0ifRHXeAqFh4rdSl6"
                publicExponent: "w367rg90jhj0asdf98gz"
            KeyGeneration:
                purpose: "signing"
                algorithm: "RSA"
                length: 2048
      responses:
        200:
        404:
        500:
      queryParameters:
        key:
    get:
      description: Retrieve the public key.
      securedBy: basic # User
      responses:
        200:
          body:
            application/json:
              type: PublicKeyEnvelope
              example:
                purpose: "signing"
                algorithm: "RSA"
                publicKey:
                  modulus: "FhJQl11CiY0ifRHXeAqFh4rdSl6"
                  publicExponent: "FhJQl11CiY0ifRHXeAqFh4rdSl6"

    /public.pem:
      description: Retrieve the public key in PEM format
      get:
        description: Retrieve Public Key
        securedBy: basic # User
        responses:
          200:
            body:
              application/json: # TODO

    /actions/{decryptMode}/decrypt:
      description: Decryption to be performed with the secret key. The provided examples are exhaustive.
      uriParameters:
        decryptMode:
          enum: ["RSA/NONE/NoPadding", "RSA/NONE/PKCS1Padding", "RSA/None/OAEPWithMd5AndMGF1Padding", "RSA/None/OAEPWithSha1AndMGF1Padding", "RSA/None/OAEPWithSha224AndMGF1Padding", "RSA/None/OAEPWithSha256AndMGF1Padding", "RSA/None/OAEPWithSha384AndMGF1Padding", "RSA/None/OAEPWithSha512AndMGF1Padding"]
      post:
        securedBy: basic # User
        body:
          application/json:
            type: object
            properties:
              encrypted: string
            example:
              encrypted: "nhrfotu32409ru0rgert45z54z099u23r03498uhtr"
        responses:
          200:
            body:
              application/json:
                type: object
                properties:
                  status: string
                  data:
                    type: object
                    properties:
                      decrypted: string
                example:
                  status: "ok"
                  data:
                    decrypted: "nhrfotu32409ru0rgert45z54z099u23r03498uhtr"
          404:
          500:

    /actions/{signMode}/sign:
      description: Signature to be performed with the secret key. The provided examples are exhaustive.
      uriParameters:
        signMode:
          enum: ["pkcs1", "pss/md5", "pss/sha1", "pss/sha224", "pss/sha256", "pss/sha384", "pss/sha512"]
      post:
        securedBy: basic # User
        body:
          application/json:
            type: object
            properties:
              message: string
            example:
              message: "this is a message"
        responses:
          200:
            body:
              application/json:
                type: object
                properties:
                  status: string
                  data:
                    type: object
                    properties:
                      signedMessage: string
                example:
                  status: "ok"
                  data:
                    signedMessage: "nhrfotu32409ru0rgert45z54z099u23r03498uhtr"
          404:
          500:

/system:
  /passwords:
      /admin:
        description: Admin Password is required to authenticate system modifications. It has to be defined before a new device can be used.
        put:
          description: Activate or change the password. The default password is empty.
          securedBy: basic # Administrator
          body:
            application/json:
              type: PasswordChange
              example:
                newPassword: "mysupersecretpassword"
          responses:
            200:
            404:
            500:
      /boot:
        description: The Boot Password is required to unlock a freshly booted system. It's optional. Alternatively the User Password is used. TODO
        post:
          description: Activate or change the password. Basic Authentication is required for changing but not activating.
          securedBy: [null, basic] # Boot
          body:
            application/json:
              type: PasswordChange
              example:
                newPassword: "nhrfotu32409ru0rgert45z54z099u23r03498uhtr"
          responses:
            200:
            404:
            500:
        delete:
          queryParameters:
          securedBy: basic # Administrator, Boot
          description: Deactivate the password
          responses:
            200:
            404:
            500:
      /user:
        description: User Password is required to execute operations.
        put:
          description: Activate or change the password.
          securedBy: basic # Administrator, User?
          body:
            application/json:
              type: PasswordChange
              example:
                newPassword: "anotherGoodPassword"
          responses:
            200:
            404:
            500:
  /information:
    get:
      description: Provides information about the vendor, product, version
      securedBy: null
      responses:
        200:
          body:
            application/json:
              type: SystemInformation
            example:
              vendor: keyfender
              product: keyfender
              version: "1.0"
  /serial:
    description: The system's serial number should be derived from some hardware serials (e.g. CPU ID). TODO
    get:
  /status:
    description: The current system status.
    get:
      securedBy: null
      responses:
        200:
          body:
            application/json:
              type: object
              properties:
                status: string
              example:
                status: "ok"
  /firmware:
    post:
      description: Update the firmware. TODO
      securedBy: basic # Administrator
      body:
        application/json:
          #TODO
      responses:
        200:
        500:
    /version:
      description: The version of the installed firmware.
      get:
        description: Retrieve the current firmware version
        securedBy: null
        responses:
          200:
          500:
  /keys:
    description: Keys for the system. TODO
    /firmware/public:
      description: The public key is used to verify signed firmware updates.
      get:
        description: Retrieve public key
        securedBy: basic # Administrator
        body:
          application/json:
        responses:
          200:
            body:
              application/json:
                type: object
                properties:
                  purpose: string
                  algorithm: string
                  publicKey: PublicRsaKey
                example:
                  purpose: "signing"
                  algorithm: "RSA"
                  publicKey:
                    modulus: "FhJQl11CiY0ifRHXeAqFh4rdSl6"
                    publicExponent: "FhJQl11CiY0ifRHXeAqFh4rdSl6"
          404:
          500:
      post:
        description: Import the public key to the keyfender
        securedBy: basic # Administrator
        body:
          application/json:
            type: object
            properties:
              purpose: string
              algorithm: string
              publicKey: PublicRsaKey
        responses:
          200:
          404:
          500:
      delete:
        description: Delete the public key. No firmware updates will be possible without a public key.
        securedBy: basic # Administrator
        responses:
          200:
          404:
          500:
    /tls:
      description: This key pair and certificate are used for HTTPS/TLS.
      post:
        description: Import or generate a key pair in(to) the keyfender.
        securedBy: basic # Administrator
        body:
          application/json:
            type: KeyImport | KeyGeneration
            examples:
              KeyImport:
                purpose: "signing"
                algorithm: "RSA"
                privateKey:
                  primeP: "frtz7u89gft89uz"
                  primeQ: "FhJQl11CiY0ifRHXeAqFh4rdSl6"
                  publicExponent: "w367rg90jhj0asdf98gz"
              KeyGeneration:
                  purpose: "signing"
                  algorithm: "RSA"
                  length: 2048
        responses:
          200:
          500:
      /public:
        description: The public key
        get:
          description: Retrieve Public Key
          responses:
            200:
              body:
                application/json:
                  type: object
                  properties:
                    purpose: string
                    algorithm: string
                    publicKey: PublicRsaKey
                  example:
                    purpose: "signing"
                    algorithm: "RSA"
                    publicKey:
                      modulus: "FhJQl11CiY0ifRHXeAqFh4rdSl6"
                      publicExponent: "FhJQl11CiY0ifRHXeAqFh4rdSl6"
            404:
      /certificate:
        description: The X.509 certificate
        get:
        post:
          securedBy: basic # Administrator
          body:
            #TODO
  /network:
    description: The network settings. TODO
    /ipv4:
      get:
      post:
        securedBy: basic # Administrator
        body:
          application/json:
            type: object
            properties:
              address: string
              netmask: string
              gateway: string
            example:
              address: "123.456.789.123"
              netmask: "255.255.255.255"
              gateway: "1.1.1.1"
    /ipv6:
      get:
      post:
        securedBy: basic # Administrator
        body:
          application/json:
            type: object
            properties:
              address: string
              netmask: string
              gateway: string
            example:
              address: "2001:0db8:0:f101::1/64"
              netmask: "64"
              gateway: "fe80::1"
  /lock:
    description: Lock an unlocked system so that no operations are possible anymore until it is unlocked again. TODO
    post:
      securedBy: basic # Administrator, Boot or User
  /reboot:
    description: Reboot the system TODO
    post:
      securedBy: basic # Administrator
  /shutdown:
    description: Shutdown and poweroff the system. TODO
    post:
      securedBy: basic # Administrator
  /unlock:
    description: Unlock and decrypt all critical data (e.g. keys) after a fresh boot or locking. TODO
    post:
      securedBy: basic # Boot
