openapi: 3.0.0
info:
title: Quantum Origin API
description: Quantum Origin API
version: 1.1.0
servers:
- url: https://qo-us.cambridgequantum.com/api/v1
description: Quantum Origin API US Server, version 1
paths:
/keygen:
post:
summary: Generate and retrieve a new key
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/KeyParameters'
responses:
'200':
description: A JSON object containing an encrypted key encoded as a base64 string
content:
application/json:
schema:
$ref: '#/components/schemas/EncryptedKeyResponse'
/randomness:
post:
summary: Retrieve quantum randomness
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RandomnessParameters'
responses:
'200':
description: A JSON object containing encrypted randomness encoded as a base64 string
content:
application/json:
schema:
$ref: '#/components/schemas/EncryptedRandomnessResponse'
/usage:
get:
summary: Get usage information
parameters:
- in: query
name: from
description: Request usage only for a period starting from the specified date
schema:
type: string
format: date
- in: query
name: to
description: Request usage only for a period ending at the specified date
schema:
type: string
format: date
- in: query
name: group_by
description: Group usage
schema:
type: string
enum: [KEY-TYPE, MONTH, MONTH-AND-KEY-TYPE, TOTAL]
default: TOTAL
responses:
'200':
description: A JSON object containing the requested usage counts
content:
application/json:
schema:
$ref: '#/components/schemas/UsageResponse'
/onboard:
post:
summary: Onboard a user with Azure subscription ID.
security:
- QOApiKey: []
parameters:
- in: header
name: onboarding-auth
schema:
type: string
required: true
description: The onboarding secret
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OnboardingPublicKey'
responses:
'200':
description: Onboarding response
content:
application/json:
schema:
$ref: '#/components/schemas/OnboardingResponse'
components:
securitySchemes:
QOApiKey:
type: apiKey
in: header
name: qo-api-key
schemas:
KeyType:
type: string
enum: [AES, RSA, EC, BIKE, CLASSIC-MCELIECE, HQC, KYBER, NTRU-PRIME, DILITHIUM, FALCON, SPHINCS]
EncryptionScheme:
description: |
The encryption scheme to be used for the response.
HKDF-AES-GCM: HKDF is used to derive a key from the shared secret and a random seed, which is used to GCM
encrypt the data with the nonce in the authenticated data.
AES-KW-CMAC: A random seed is encrypted with the shared secret to derive a wrapping key, then AES key wrapping
is used to encrypt the data with the wrapping key. A CMAC is also calculated over the
concatenation of the nonce and the encrypted data.
type: string
enum: [HKDF-AES-GCM, AES-KW-CMAC]
default: HKDF-AES-GCM
RandomnessParameters:
type: object
properties:
size:
type: integer
minimum: 1
maximum: 2097152
nonce:
description: A unique value to protect against replay attacks
type: string
format: byte
nonces:
description: An array of unique values to protect against replay attacks
type: array
items:
type: string
format: byte
encryption_scheme:
$ref: '#/components/schemas/EncryptionScheme'
required:
- size
OnboardingPublicKey:
type: object
properties:
onboarding_public_key:
description: The public key of the onboarding secp521r1 key pair
type: string
OnboardingResponse:
description: Onboarding response
type: object
properties:
qo_api_uid:
description: A new UID for the subsequent API calls
type: string
transport_key:
description: A secp521r1 public key to derive the AES key to encrypt the encrypted-secret
type: string
encrypted_secret:
description: Encrypted version of the final shared secret
type: string
KeyParameters:
type: object
properties:
key_type:
$ref: '#/components/schemas/KeyType'
key_parameters:
oneOf:
- $ref: '#/components/schemas/AesKeyParameters'
- $ref: '#/components/schemas/RsaKeyParameters'
- $ref: '#/components/schemas/ECKeyParameters'
- $ref: '#/components/schemas/BikeKeyParameters'
- $ref: '#/components/schemas/ClassicMcElieceKeyParameters'
- $ref: '#/components/schemas/HqcKeyParameters'
- $ref: '#/components/schemas/KyberKeyParameters'
- $ref: '#/components/schemas/NtruPrimeKeyParameters'
- $ref: '#/components/schemas/DilithiumKeyParameters'
- $ref: '#/components/schemas/FalconKeyParameters'
- $ref: '#/components/schemas/SphincsKeyParameters'
nonce:
description: A unique value to protect against replay attacks
type: string
format: byte
encryption_scheme:
$ref: '#/components/schemas/EncryptionScheme'
include_public:
description: |
Whether to include the unencrypted public key as a separate field in the response (only applies
to asymmetric key-types)
type: boolean
default: false
public_key:
description: |
PEM-encoded RSA public key. If provided the key to be returned will be encrypted using this public key, in
addition to being encrypted using the client's shared secret. Encryption under this public key is done
first, then the result of that encryption is encrypted using the shared secret.
The algorithm used will be RSA-OAEP with MGF1 and the hash function specified in the `oaep_parameters`
(default SHA-256).
If `aes_key_wrap` is false, this requires that the key being encrypted is no longer in bytes than the
modulus of the RSA key minus 66 bytes (if using SHA-256 hash function) or minus 42 bytes (if using SHA-1
hash function).
type: string
aes_key_wrap:
description: |
Whether to use AES key wrapping with an ephemeral AES wrapping key.
Only applies if `public_key` is also provided.
If false the key to be returned is wrapped directly using the given public key.
If true, an ephemeral AES key is used to encrypt the key to be returned using NIST KWP (NIST SP800-38F).
This AES key is then encrypted using the supplied RSA public key, and both encrypted keys are concatenated
before being finally encrypted using the shared secret.
type: boolean
default: false
oaep_hash_function:
description: Hash function to be used in the OAEP padding. Only applies if `public_key` is also provided.
type: string
enum: [SHA-1, SHA-256]
default: SHA-256
required:
- key_type
- key_parameters
- nonce
AesKeyParameters:
type: object
properties:
size:
description: AES key size in bits
type: integer
enum: [128, 192, 256]
format:
description: Key format (when decrypted)
type: string
enum: [RAW, PKCS8]
default: RAW
required:
- size
RsaKeyParameters:
type: object
properties:
size:
description: RSA key size in bits
type: integer
minimum: 1024
maximum: 8192
exponent:
type: integer
description: RSA key exponent
default: 65537
format:
description: Key format (when decrypted)
type: string
enum: [PKCS1, PKCS8]
default: PKCS1
required:
- size
ECKeyParameters:
type: object
properties:
curve:
type: string
enum: [Bp256r1, Bp384r1, Bp512r1, SecP192k1, SecP192r1, SecP224k1, SecP224r1, SecP256k1, SecP256r1, SecP384r1, SecP521r1, X25519]
format:
description: Key format (when decrypted)
type: string
enum: [SEC1, PKCS8]
default: SEC1
required:
- curve
BikeKeyParameters:
type: object
properties:
variant:
type : string
enum: [BIKE-L1, BIKE-L3]
required:
- variant
ClassicMcElieceKeyParameters:
type: object
properties:
variant:
type : string
enum: [CLASSIC-MCELIECE-348864, CLASSIC-MCELIECE-348864f, CLASSIC-MCELIECE-460896, CLASSIC-MCELIECE-460896f, CLASSIC-MCELIECE-6688128, CLASSIC-MCELIECE-6688128f, CLASSIC-MCELIECE-6960119, CLASSIC-MCELIECE-6960119f, CLASSIC-MCELIECE-8192128, CLASSIC-MCELIECE-8192128f]
required:
- variant
HqcKeyParameters:
type: object
properties:
variant:
type : string
enum: [HQC-128, HQC-192, HQC-256]
required:
- variant
KyberKeyParameters:
type: object
properties:
variant:
type: string
enum: [KYBER512, KYBER512-90s, KYBER768, KYBER768-90s, KYBER1024, KYBER1024-90s]
required:
- variant
NtruPrimeKeyParameters:
type: object
properties:
variant:
type: string
enum: [NTRULPR-653, NTRULPR-761, NTRULPR-857, NTRULPR-1277, SNTRUP-653, SNTRUP-761, SNTRUP-857, SNTRUP-1277]
required:
- variant
DilithiumKeyParameters:
type: object
properties:
variant:
type: string
enum: [DILITHIUM2, DILITHIUM3, DILITHIUM5, DILITHIUM2-AES, DILITHIUM3-AES, DILITHIUM5-AES]
required:
- variant
FalconKeyParameters:
type: object
properties:
variant:
type: string
enum: [FALCON-512, FALCON-1024]
required:
- variant
SphincsKeyParameters:
type: object
properties:
variant:
type : string
enum: [
# Haraka
SPHINCS-HARAKA-128F-ROBUST, SPHINCS-HARAKA-128F-SIMPLE, SPHINCS-HARAKA-128S-ROBUST, SPHINCS-HARAKA-128S-SIMPLE,
SPHINCS-HARAKA-192F-ROBUST, SPHINCS-HARAKA-192F-SIMPLE, SPHINCS-HARAKA-192S-ROBUST, SPHINCS-HARAKA-192S-SIMPLE,
SPHINCS-HARAKA-256F-ROBUST, SPHINCS-HARAKA-256F-SIMPLE, SPHINCS-HARAKA-256S-ROBUST, SPHINCS-HARAKA-256S-SIMPLE,
# SHA256
SPHINCS-SHA256-128F-ROBUST, SPHINCS-SHA256-128F-SIMPLE, SPHINCS-SHA256-128S-ROBUST, SPHINCS-SHA256-128S-SIMPLE,
SPHINCS-SHA256-192F-ROBUST, SPHINCS-SHA256-192F-SIMPLE, SPHINCS-SHA256-192S-ROBUST, SPHINCS-SHA256-192S-SIMPLE,
SPHINCS-SHA256-256F-ROBUST, SPHINCS-SHA256-256F-SIMPLE, SPHINCS-SHA256-256S-ROBUST, SPHINCS-SHA256-256S-SIMPLE,
# Shake256
SPHINCS-SHAKE256-128F-ROBUST, SPHINCS-SHAKE256-128F-SIMPLE, SPHINCS-SHAKE256-128S-ROBUST, SPHINCS-SHAKE256-128S-SIMPLE,
SPHINCS-SHAKE256-192F-ROBUST, SPHINCS-SHAKE256-192F-SIMPLE, SPHINCS-SHAKE256-192S-ROBUST, SPHINCS-SHAKE256-192S-SIMPLE,
SPHINCS-SHAKE256-256F-ROBUST, SPHINCS-SHAKE256-256F-SIMPLE, SPHINCS-SHAKE256-256S-ROBUST, SPHINCS-SHAKE256-256S-SIMPLE,
]
required:
- variant
EncryptedKeyResponse:
allOf:
- type: object
properties:
content_type:
type: string
public:
type: string
format: byte
required:
- content_type
- $ref: '#/components/schemas/EncryptedData'
EncryptedData:
oneOf:
- $ref: '#/components/schemas/EncryptedDataHkdfAesGcm'
- $ref: '#/components/schemas/EncryptedDataAesKwHmac'
EncryptedDataHkdfAesGcm:
type: object
properties:
seed:
type: string
format: byte
counter:
type: integer
format: int64
encrypted_data:
type: string
format: byte
required:
- seed
- counter
- encrypted_data
EncryptedDataAesKwHmac:
type: object
properties:
seed:
type: string
format: byte
encrypted_data:
type: string
format: byte
mac:
type: string
format: byte
required:
- seed
- encrypted_data
- mac
EncryptedRandomnessResponse:
allOf:
- type: object
properties:
content_type:
type: string
required:
- content_type
- oneOf:
- $ref: '#/components/schemas/EncryptedData'
- type: object
properties:
batches:
type: array
items:
oneOf:
- $ref: '#/components/schemas/EncryptedData'
UsageResponse:
type: array
items:
type: object
properties:
key_type:
type: string
month:
type: string
count:
type: integer
# © Copyright 2022, Quantinuum Ltd ["Quantinuum"].