Skip to main content

Create or install security certificates

Contributors
PDFs

POST /security/certificates

Introduced In: 9.6

Creates or installs a certificate or downloads a certificate from Azure Key Vault (AKV) and installs it on the ONTAP cluster.

Required properties

  • svm.uuid or svm.name - Existing SVM in which to create or install the certificate.

  • common_name - Common name of the certificate. Required when creating a certificate.

  • type - Type of certificate.

  • public_certificate - Public key certificate in PEM format. Required when installing a certificate.

  • private_key - Private key certificate in PEM format. Required when installing a CA-signed certificate.

  • expiry_time - Certificate expiration time. Specifying an expiration time is recommended when creating a certificate.

  • key_size - Key size of the certificate in bits. Specifying a strong key size is recommended when creating a certificate.

  • name - Unique certificate name per SVM or the name of the certificate in AKV, required for downloading AKV certificates. If one is not provided, it is automatically generated.

AKV required properties for downloading a certificate

  • azure.key_vault - URI of the Azure Key Vault.

  • azure.client_id - Application (client) ID of the deployed Azure application with appropriate access to an AKV.

  • azure.tenant_id - Directory (tenant) ID of the deployed Azure application with appropriate access to an AKV.

  • azure.client_secret - Secret used by the application to prove its identity to AKV.

  • azure.client_certificate - PKCS12 certificate used by the application to prove its identity to AKV.

AKV optional properties for downloading a certificate

  • azure.oauth_host - Open authorization server host name.

  • azure.proxy.type - Type of proxy (http, https etc.) if proxy configuration is used.

  • azure.proxy.host - Proxy hostname if proxy configuration is used.

  • azure.proxy.port - Proxy port number if proxy configuration is used.

  • azure.proxy.username - Proxy username if proxy configuration is used.

  • azure.proxy.password - Proxy password if proxy configuration is used.

  • azure.timeout - AKV connection timeout in seconds.

  • azure.verify_host - Verify the identity of the AKV host name.

Default property values

If not specified in POST, the following default property values are assigned:

  • key_size - 2048

  • expiry_time - P365DT

  • hash_function - sha256

  • security certificate create

  • security certificate install

  • security certificate azure-install

Parameters

Name Type In Required Description

return_records

boolean

query

False

The default is false. If set to true, the records are returned.

  • Default value:

Request Body

Name Type Description

_links

_links

authority_key_identifier

string

Provides the key identifier of the issuing CA certificate that signed the SSL certificate.

azure

azure

ca

string

Certificate authority

common_name

string

FQDN or custom common name. Provide on POST when creating a self-signed certificate.

expiry_time

string

Certificate expiration time. Can be provided on POST if creating self-signed certificate. The expiration time range is between 1 day to 10 years.

hash_function

string

Hashing function. Can be provided on POST when creating a self-signed certificate. Hash functions md5 and sha1 are not allowed on POST.

intermediate_certificates

array[string]

Chain of intermediate Certificates in PEM format. Only valid in POST when installing a certificate.

key_size

integer

Key size of requested Certificate in bits. One of 512, 1024, 1536, 2048, 3072. Can be provided on POST if creating self-signed certificate with a minimum permissible value of 2048.

name

string

Certificate name or name of the certificate to be downloaded from the Azure Key Vault (AKV). If not provided in POST, a unique name specific to the SVM is automatically generated.

private_key

string

Private key Certificate in PEM format. Only valid for create when installing a CA-signed certificate. This is not audited.

public_certificate

string

Public key Certificate in PEM format. If this is not provided in POST, a self-signed certificate is created.

scope

string

Set to "svm" for interfaces owned by an SVM. Otherwise, set to "cluster".

serial_number

string

Serial number of certificate.

subject_key_identifier

string

Provides the key identifier used to identify the public key in the SSL certificate.

svm

svm

SVM, applies only to SVM-scoped objects.

type

string

Type of Certificate. The following types are supported:

  • client - a certificate and its private key used by an SSL client in ONTAP.

  • server - a certificate and its private key used by an SSL server in ONTAP.

  • client_ca - a Certificate Authority certificate used by an SSL server in ONTAP to verify an SSL client certificate.

  • server_ca - a Certificate Authority certificate used by an SSL client in ONTAP to verify an SSL server certificate.

  • root_ca - a self-signed certificate used by ONTAP to sign other certificates by acting as a Certificate Authority.

  • enum: ["client", "server", "client_ca", "server_ca", "root_ca"]

  • Introduced in: 9.6

  • x-nullable: true

uuid

string

Unique ID that identifies a certificate.
Example request 
{
  "_links": {
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "authority_key_identifier": "26:1F:C5:53:5B:D7:9E:E2:37:74:F4:F4:06:09:03:3D:EB:41:75:D7",
  "azure": {
    "client_certificate": "PEM Cert",
    "client_id": "aaaaaaaa-bbbb-aaaa-bbbb-aaaaaaaaaaaa",
    "client_secret": "abcdef",
    "key_vault": "https://kmip-akv-keyvault.vault.azure.net/",
    "oauth_host": "login.microsoftonline.com",
    "proxy": {
      "host": "proxy.eng.com",
      "password": "proxypassword",
      "port": 1234,
      "type": "http",
      "username": "proxyuser"
    },
    "tenant_id": "zzzzzzzz-yyyy-zzzz-yyyy-zzzzzzzzzzzz",
    "timeout": 25
  },
  "ca": "string",
  "common_name": "test.domain.com",
  "hash_function": "sha1",
  "intermediate_certificates": {
  },
  "private_key": "-----BEGIN PRIVATE KEY-----\\nprivate-key\\n-----END PRIVATE KEY-----\\n",
  "public_certificate": "-----BEGIN CERTIFICATE----- MIIBuzCCAWWgAwIBAgIIFTZBrqZwUUMwDQYJKoZIhvcNAQELBQAwHDENMAsGA1UE AxMEVEVTVDELMAkGA1UEBhMCVVMwHhcNMTgwNjA4MTgwOTAxWhcNMTkwNjA4MTgw OTAxWjAcMQ0wCwYDVQQDEwRURVNUMQswCQYDVQQGEwJVUzBcMA0GCSqGSIb3DQEB AQUAA0sAMEgCQQDaPvbqUJJFJ6NNTyK3Yb+ytSjJ9aa3yUmYTD9uMiP+6ycjxHWB e8u9z6yCHsW03ync+dnhE5c5z8wuDAY0fv15AgMBAAGjgYowgYcwDAYDVR0TBAUw AwEB/zALBgNVHQ8EBAMCAQYwHQYDVR0OBBYEFMJ7Ev/o/3+YNzYh5XNlqqjnw4zm MEsGA1UdIwREMEKAFMJ7Ev/o/3+YNzYh5XNlqqjnw4zmoSCkHjAcMQ0wCwYDVQQD EwRURVNUMQswCQYDVQQGEwJVU4IIFTZBrqZwUUMwDQYJKoZIhvcNAQELBQADQQAv DovYeyGNnknjGI+TVNX6nDbyzf7zUPqnri0KuvObEeybrbPW45sgsnT5dyeE/32U 9Yr6lklnkBtVBDTmLnrC -----END CERTIFICATE-----",
  "scope": "svm",
  "serial_number": "string",
  "subject_key_identifier": "26:1F:C5:53:5B:D7:9E:E2:37:74:F4:F4:06:09:03:3D:EB:41:75:D8",
  "svm": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "name": "svm1",
    "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
  },
  "type": "client",
  "uuid": "string"
}

Response

Status: 201, Created
Name Type Description

_links

_links

num_records

integer

Number of records

records

array[security_certificate]
Example response 
{
  "_links": {
    "next": {
      "href": "/api/resourcelink"
    },
    "self": {
      "href": "/api/resourcelink"
    }
  },
  "num_records": 1,
  "records": {
    "_links": {
      "self": {
        "href": "/api/resourcelink"
      }
    },
    "authority_key_identifier": "26:1F:C5:53:5B:D7:9E:E2:37:74:F4:F4:06:09:03:3D:EB:41:75:D7",
    "azure": {
      "client_certificate": "PEM Cert",
      "client_id": "aaaaaaaa-bbbb-aaaa-bbbb-aaaaaaaaaaaa",
      "client_secret": "abcdef",
      "key_vault": "https://kmip-akv-keyvault.vault.azure.net/",
      "oauth_host": "login.microsoftonline.com",
      "proxy": {
        "host": "proxy.eng.com",
        "password": "proxypassword",
        "port": 1234,
        "type": "http",
        "username": "proxyuser"
      },
      "tenant_id": "zzzzzzzz-yyyy-zzzz-yyyy-zzzzzzzzzzzz",
      "timeout": 25
    },
    "ca": "string",
    "common_name": "test.domain.com",
    "hash_function": "sha1",
    "intermediate_certificates": {
    },
    "private_key": "-----BEGIN PRIVATE KEY-----\\nprivate-key\\n-----END PRIVATE KEY-----\\n",
    "public_certificate": "-----BEGIN CERTIFICATE----- MIIBuzCCAWWgAwIBAgIIFTZBrqZwUUMwDQYJKoZIhvcNAQELBQAwHDENMAsGA1UE AxMEVEVTVDELMAkGA1UEBhMCVVMwHhcNMTgwNjA4MTgwOTAxWhcNMTkwNjA4MTgw OTAxWjAcMQ0wCwYDVQQDEwRURVNUMQswCQYDVQQGEwJVUzBcMA0GCSqGSIb3DQEB AQUAA0sAMEgCQQDaPvbqUJJFJ6NNTyK3Yb+ytSjJ9aa3yUmYTD9uMiP+6ycjxHWB e8u9z6yCHsW03ync+dnhE5c5z8wuDAY0fv15AgMBAAGjgYowgYcwDAYDVR0TBAUw AwEB/zALBgNVHQ8EBAMCAQYwHQYDVR0OBBYEFMJ7Ev/o/3+YNzYh5XNlqqjnw4zm MEsGA1UdIwREMEKAFMJ7Ev/o/3+YNzYh5XNlqqjnw4zmoSCkHjAcMQ0wCwYDVQQD EwRURVNUMQswCQYDVQQGEwJVU4IIFTZBrqZwUUMwDQYJKoZIhvcNAQELBQADQQAv DovYeyGNnknjGI+TVNX6nDbyzf7zUPqnri0KuvObEeybrbPW45sgsnT5dyeE/32U 9Yr6lklnkBtVBDTmLnrC -----END CERTIFICATE-----",
    "scope": "svm",
    "serial_number": "string",
    "subject_key_identifier": "26:1F:C5:53:5B:D7:9E:E2:37:74:F4:F4:06:09:03:3D:EB:41:75:D8",
    "svm": {
      "_links": {
        "self": {
          "href": "/api/resourcelink"
        }
      },
      "name": "svm1",
      "uuid": "02c9e252-41be-11e9-81d5-00a0986138f7"
    },
    "type": "client",
    "uuid": "string"
  }
}

Headers

Name Description Type

Location

Useful for tracking the resource location

string

Error

Status: Default

ONTAP Error Response Codes

Error Code Description

3735645

Cannot specify a value for serial. It is generated automatically.

3735622

The certificate type is not supported.

3735664

The specified key size is not supported in FIPS mode.

3735665

The specified hash function is not supported in FIPS mode.

3735553

Failed to create self-signed Certificate.

3735646

Failed to store the certificates.

3735693

The certificate installation failed as private key was empty.

3735618

Cannot accept private key for server_ca or client_ca.

52363365

Failed to allocate memory.

52559975

Failed to read the certificate due to incorrect formatting.

52363366

Unsupported key type.

52560123

Failed to read the key due to incorrect formatting.

52559972

The certificates start date is later than the current date.

52559976

The certificate and private key do not match.

52559973

The certificate has expired.

52363366

Logic error: use of a dead object.

3735696

Intermediate certificates are not supported with client_ca and server_ca type certificates.

52559974

The certificate is not supported in FIPS mode.

3735676

Cannot continue the installation without a value for the common name. Since the subject field in the certificate is empty, the field "common_name" must have a value to continue with the installation.

3735558

Failed to extract information about Common Name from the certificate.

3735588

The common name (CN) extracted from the certificate is not valid.

3735632

Failed to extract Certificate Authority Information from the certificate.

3735700

The specified key size is not supported.

52560173

The hash function is not supported for digital signatures.

3735751

Failed to authenticate and fetch the access token from Azure OAuth host.

3735752

Failed to extract the private key from the Azure Key Vault certificate.

3735753

Unsupported content_type in the Azure secrets response.

3735754

Internal error. Failed to parse the JSON response from Azure Key Vault.

3735755

REST call to Azure failed.

3735756

Invalid client certificate.

3735757

Internal error. Failed to generate client assertion.

3735762

Provided Azure Key Vault configuration is incorrect.

3735763

Provided Azure Key Vault configuration is incomplete.

3735764

Name Type Description

error

returned_error
Example error 
{
  "error": {
    "arguments": {
      "code": "string",
      "message": "string"
    },
    "code": "4",
    "message": "entry doesn't exist",
    "target": "uuid"
  }
}

Definitions

See Definitions

href

Name Type Description

href

string

_links

Name Type Description

self

href

proxy

Name Type Description

host

string

Proxy host.

password

string

Proxy password. Password is not audited.

port

integer

Proxy port.

type

string

Proxy type.

username

string

Proxy username.

azure

Name Type Description

client_certificate

string

PKCS12 certificate used by the application to prove its identity to AKV.

client_id

string

Application client ID of the deployed Azure application with appropriate access to an AKV.

client_secret

string

Secret used by the application to prove its identity to AKV.

key_vault

string

URI of the deployed AKV that is used by ONTAP for storing keys.

oauth_host

string

Open authorization server host name.

proxy

proxy

tenant_id

string

Directory (tenant) ID of the deployed Azure application with appropriate access to an AKV.

timeout

integer

AKV connection timeout, in seconds. The allowed range is between 0 to 30 seconds.

verify_host

boolean

Verify the identity of the AKV host name. By default, verify_host is set to true.

svm

SVM, applies only to SVM-scoped objects.

Name Type Description

_links

_links

name

string

The name of the SVM. This field cannot be specified in a PATCH method.

uuid

string

The unique identifier of the SVM. This field cannot be specified in a PATCH method.

security_certificate

Name Type Description

_links

_links

authority_key_identifier

string

Provides the key identifier of the issuing CA certificate that signed the SSL certificate.

azure

azure

ca

string

Certificate authority

common_name

string

FQDN or custom common name. Provide on POST when creating a self-signed certificate.

expiry_time

string

Certificate expiration time. Can be provided on POST if creating self-signed certificate. The expiration time range is between 1 day to 10 years.

hash_function

string

Hashing function. Can be provided on POST when creating a self-signed certificate. Hash functions md5 and sha1 are not allowed on POST.

intermediate_certificates

array[string]

Chain of intermediate Certificates in PEM format. Only valid in POST when installing a certificate.

key_size

integer

Key size of requested Certificate in bits. One of 512, 1024, 1536, 2048, 3072. Can be provided on POST if creating self-signed certificate with a minimum permissible value of 2048.

name

string

Certificate name or name of the certificate to be downloaded from the Azure Key Vault (AKV). If not provided in POST, a unique name specific to the SVM is automatically generated.

private_key

string

Private key Certificate in PEM format. Only valid for create when installing a CA-signed certificate. This is not audited.

public_certificate

string

Public key Certificate in PEM format. If this is not provided in POST, a self-signed certificate is created.

scope

string

Set to "svm" for interfaces owned by an SVM. Otherwise, set to "cluster".

serial_number

string

Serial number of certificate.

subject_key_identifier

string

Provides the key identifier used to identify the public key in the SSL certificate.

svm

svm

SVM, applies only to SVM-scoped objects.

type

string

Type of Certificate. The following types are supported:

  • client - a certificate and its private key used by an SSL client in ONTAP.

  • server - a certificate and its private key used by an SSL server in ONTAP.

  • client_ca - a Certificate Authority certificate used by an SSL server in ONTAP to verify an SSL client certificate.

  • server_ca - a Certificate Authority certificate used by an SSL client in ONTAP to verify an SSL server certificate.

  • root_ca - a self-signed certificate used by ONTAP to sign other certificates by acting as a Certificate Authority.

  • enum: ["client", "server", "client_ca", "server_ca", "root_ca"]

  • Introduced in: 9.6

  • x-nullable: true

uuid

string

Unique ID that identifies a certificate.

_links

Name Type Description

next

href

self

href

error_arguments

Name Type Description

code

string

Argument code

message

string

Message argument

returned_error

Name Type Description

arguments

array[error_arguments]

Message arguments

code

string

Error code

message

string

Error message

target

string

The target parameter that caused the error.