You are here

Vault API & S3 Compliance Guide

Nicman Vault Documentation

API & S3 Compliance Guide


1. Introduction

The Nicman Vault system supports most of the Amazon S3 REST API, including advanced features.

This document provides the details of the Vault system’s compliance with the S3 REST API. The organization of this document parallels that of the Amazon S3 API Reference. Links are provided to specific parts of the Amazon S3 API Reference so you can easily view additional information about individual API operations.

This document takes the approach of specifying in detail the things that the Vault system does support from the Amazon S3 REST API — from service, bucket, and object operations, down to the level of particular request parameters, request headers, request elements, response headers, response elements, and special errors. If it’s not listed in this document, the Vault system does not currently support it.

This document also describes ways in which the Vault system extends the Amazon S3 API, to support additional functionality. There are two categories of Vault extensions to the Amazon S3 API:

  • Additional operations on buckets. In this document these are listed after the standard Amazon S3 operations on buckets. The sections describing these operations have titles indicating that they are extensions, such as "PUT Bucket Storage Type (Vault Extension)".

  • Extensions to standard Amazon S3 operations on buckets or objects. For example, these may be additional request parameters or request headers that provide enhanced functionality for an Amazon S3 operation. These extensions are described within the sections that document Vault compliance with specific Amazon S3 operations. The extensions are always identified by a sub-heading that says "Vault Extension to the S3 API".

2. Error Responses

From the "Error Responses" section of the Amazon S3 API, the Vault system supports the error codes listed below. If an error code from the Amazon S3 API specification is not listed below, the Vault system does not support it. For error descriptions and for mapping of these errors to HTTP status codes, refer to the "Error Responses" section of the Amazon S3 API.

  • AccessDenied

  • AccountProblem

  • AmbiguousGrantByEmailAddress

  • BadDigest

  • BucketAlreadyExists

  • BucketAlreadyOwnedByYou

  • BucketNotEmpty

  • CrossLocationLoggingProhibited

  • EntityTooLarge

  • IllegalVersioningConfigurationException

  • IncorrectNumberOfFilesInPostRequest

  • InternalError

  • InvalidAccessKeyId

  • InvalidArgument

  • InvalidBucketName

  • InvalidBucketState

  • InvalidDigest

  • InvalidLocationConstraint

  • InvalidObjectState

  • InvalidPart

  • InvalidPartOrder

  • InvalidPolicyDocument

  • InvalidRange

  • InvalidRequest

  • InvalidSecurity

  • InvalidTargetBucketForLogging

  • InvalidURI

  • KeyTooLong

  • MalformedACLError

  • MalformedPOSTRequest

  • MalformedXML

  • MaxMessageLengthExceeded

  • MaxPostPreDataLengthExceededError

  • MetadataTooLarge

  • MethodNotAllowed

  • MissingContentLength

  • NoSuchBucket

  • NoSuchKey

  • NoSuchLifecycleConfiguration

  • NoSuchUpload

  • NoSuchVersion

  • NotImplemented

  • PermanentRedirect

  • PreconditionFailed

  • Redirect

  • RestoreAlreadyInProgress

  • RequestIsNotMultiPartContent

  • RequestTimeTooSkewed

  • SignatureDoesNotMatch

  • ServiceUnavailable

  • SlowDown

  • TemporaryRedirect

  • TooManyBuckets

  • UnresolvableGrantByEmailAddress

  • UserKeyMustBeSpecified

2.1. REST Error Format

The Vault system supports the same REST error format specified in the "REST Error Responses" section of the Amazon S3 API.

3. Common Request Headers

From the "Common Request Headers" section of the Amazon S3 REST API, the Vault system supports the headers listed below. If a common request header from the Amazon S3 API specification is not listed below, the Vault system does not support it. For header descriptions, refer to the "Common Request Headers" section of the Amazon S3 REST API.

  • Authorization

  • Content-Length

  • Content-Type

  • Content-MD5

  • Date

  • Expect

  • Host

  • x-amz-date

4. Common Response Headers

From the "Common Response Headers" section of the Amazon S3 REST API, the Vault system supports the headers listed below. If a common response header from the Amazon S3 API specification is not listed below, the Vault system does not support it. For header descriptions, refer to the "Common Response Headers" section of the Amazon S3 REST API

  • Content-Length

  • Content-Type

  • Connection

  • Date

  • ETag

  • Server

  • x-amz-delete-marker

  • x-amz-request-id

  • x-amz-version-id

5. Operations on the Service

From the "Operations on the Service" section of the Amazon S3 REST API, the Vault system supports the operations listed below. If a service operation from the Amazon S3 API specification is not listed below, the Vault system does not support it. For details of Vault support for specific operations — such as which parameters and headers are supported — click on the links.

5.1. GET Service

For the Amazon S3 "GET Service" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Service in the Amazon S3 REST API specification.

5.1.1. Response Elements

  • Bucket

  • Buckets

  • CreationDate

  • DisplayName

  • ID

  • ListAllMyBucketsResult

  • Name

  • Owner

6. Operations on Buckets

From the "Operations on Buckets" section of the Amazon S3 REST API, the Vault system supports the operations listed below. If a bucket operation from the Amazon S3 API specification is not listed below, the Vault system does not support it. For details of Vault support for specific operations — such as which parameters and headers are supported — click on the links.

As extensions to the S3 API, the Vault system also supports these operations on buckets:

6.1. DELETE Bucket

For the Amazon S3 "DELETE Bucket" operation, the Vault system supports the S3 common request headers and common response headers. For operation usage, information see DELETE Bucket in the Amazon S3 REST API specification.

6.2. DELETE Bucket cors

For the Amazon S3 "DELETE Bucket cors" operation, the Vault system supports the S3 common request headers and common response headers. For operation usage information see DELETE Bucket cors in the Amazon S3 REST API specification.

6.3. DELETE Bucket lifecycle

For the Amazon S3 "DELETE Bucket lifecycle" operation, the Vault system supports the S3 common request headers and common response headers. For operation usage information see DELETE Bucket lifecycle in the Amazon S3 REST API specification.

6.4. DELETE Bucket policy

For the Amazon S3 "DELETE Bucket policy" operation, the Vault system supports the S3 common request headers and common response headers. For operation usage information see DELETE Bucket policy in the Amazon S3 REST API specification.

6.5. DELETE Bucket website

For the Amazon S3 "DELETE Bucket website" operation, the Vault system supports the S3 common request headers and common response headers. For operation usage information see DELETE Bucket website in the Amazon S3 REST API specification.

6.6. GET Bucket (List Objects)

For the Amazon S3 "GET Bucket (List Objects)" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket (List Objects) in the Amazon S3 REST API specification.

6.6.1. Request Parameters

  • delimiter

    Note The Vault system does not support %c2%85(U+0085) as a delimiter value
  • encoding-type

  • marker

  • max-keys

  • prefix

Vault Extension to the S3 API

The Vault system supports the following Request Parameter as an extension to the "GET Bucket (List Objects)" operation:

Parameter

Description

Required

meta

You can use the request parameter meta=true to return user-defined object metadata with the GET Bucket response. Without this Vault extension, the GET Bucket method returns only system metadata, not user-defined metadata. You would have to do a GET Object on individual objects to get the user-defined object metadata. (For more information on user-defined metadata versus system metadata, see Object Key and Metadata in the Amazon S3 documentation).

If you use the meta=true option for GET Bucket, then within the XML response body the user-defined metadata will be presented as a metadata element nested in the Contents element. In the example below, the lines that follow the Owner element show how user-defined metadata will be included in the result if you use the meta=true request parameter with the GET Bucket request.

HTTP/1.1 200 OK
...

<ListBucketResult xmlns="http://s3.nicmanlab.com/2013-10-01/">
  ...
    <Contents>
        <Key>my-image.jpg</Key>
        <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>&quot;fba9dede5f27731c9771645a39863328&quot;</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID>
            <DisplayName>mtd@amazon.com</DisplayName>
        </Owner>
        <metadata name="name1">value1</metadata>
        <metadata name="name2">value2</metadata>
        <metadata name="name3">value3</metadata>
    </Contents>
    ...
  ...
</ListBucketResult>
Note

The x-amz-meta- (or x-yourservice-meta-) extension header prefixes that you use to create user-defined object metadata items (with the PUT Object operation) are not included in the metadata names in the GET Bucket response. For example, if you created a user-defined metadata item by using an x-amz-meta-groupid header in a PUT Object operation, in a GET Bucket response the metadata name would simply be groupid.

When you create user-defined object metadata (with PUT Object), the metadata values must be UTF-8 and must not contain control characters less than 0x20 except for \r, \n, and \t. Also, normal XML escaping is required where appropriate.

No (defaults to "false")

6.6.2. Response Elements

  • Contents

  • CommonPrefixes

  • Delimiter

  • DisplayName

  • Encoding-Type

  • ETag

  • ID

  • IsTruncated

  • Key

  • LastModified

  • Marker

  • MaxKeys

  • Name

  • NextMarker

  • Owner

  • Prefix

  • Size

  • StorageClass (values STANDARD and GLACIER only)

Vault Extension to the S3 API

The Vault system supports a metadata response element as described in the Request Parameters section above.

6.7. GET Bucket acl

For the Amazon S3 "GET Bucket acl" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket acl in the Amazon S3 REST API specification.

6.7.1. Response Elements

  • AccessControlList

  • AccessControlPolicy

  • DisplayName

  • Grant

  • Grantee

  • ID

  • Owner

  • Permission

6.8. GET Bucket cors

For the Amazon S3 "GET Bucket cors" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket cors in the Amazon S3 REST API specification.

6.8.1. Response Elements

  • CORSConfiguration

  • CORSRule

  • AllowedHeader

  • AllowedMethod

  • AllowedOrigin

  • ExposeHeader

  • ID

  • MaxAgeSeconds

6.9. GET Bucket lifecycle

For the Amazon S3 "GET Bucket lifecycle" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket lifecycle in the Amazon S3 REST API specification.

6.9.1. Response Headers

Vault Extension to the S3 API

The Vault system supports the following Response Headers as extensions to the "GET Bucket lifecycle" operation:

Parameter

Description

Required

x-gmt-tieringinfo

No

x-gmt-compare

No

6.9.2. Response Elements

  • Date

  • Days

  • Expiration

  • ID

  • LifecycleConfiguration

  • Prefix

  • Rule

  • Status

  • StorageClass

  • Transition

6.9.3. Special Errors

  • NoSuchLifecycleConfiguration

6.10. GET Bucket policy

For the Amazon S3 "GET Bucket policy" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket policy in the Amazon S3 REST API specification.

6.10.1. Response Elements

The response contains the (JSON) policy of the specified bucket.

6.11. GET Bucket location

For the Amazon S3 "GET Bucket location" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket location in the Amazon S3 REST API specification.

6.11.1. Response Elements

  • LocationConstraint

6.12. GET Bucket logging

For the Amazon S3 "GET Bucket logging" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket logging in the Amazon S3 REST API specification.

6.12.1. Response Elements

  • BucketLoggingStatus

  • Grant

  • Grantee

  • LoggingEnabled

  • Permission

  • TargetBucket

  • TargetGrants

  • TargetPrefix

6.13. GET Bucket Object versions

For the Amazon S3 "GET Bucket Object versions" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket Object versions in the Amazon S3 REST API specification.

6.13.1. Request Parameters

  • delimiter

  • encoding-type

  • key-marker

  • max-keys

  • prefix

  • version-id-marker

Vault Extension to the S3 API

The Vault system supports an optional request parameter meta=true. This extension works exactly as described for GET Bucket (List Objects), except that for "GET Bucket Object Versions", in the response body the metadata element will be nested in the Version element and DeleteMarker element of the ListVersionsResult object.

6.13.2. Response Elements

  • DeleteMarker

  • DisplayName

  • Encoding-Type

  • ETag

  • ID

  • IsLatest

  • IsTruncated

  • Key

  • KeyMarker

  • LastModified

  • ListVersionsResult

  • MaxKeys

  • Name

  • NextKeyMarker

  • NextVersionIdMarker

  • Owner

  • Prefix

  • Size

  • StorageClass

  • Version

  • VersionId

  • VersionIdMarker

Vault Extension to the S3 API

The Vault system supports a metadata response element, which presents user-defined metadata. This extension works exactly as described for GET Bucket (List Objects), except that for "GET Bucket Object Versions", in the response body the metadata element will be nested in the Version element and DeleteMarker element of the ListVersionsResult object.

6.14. GET Bucket versioning

For the Amazon S3 "GET Bucket versioning" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket versioning in the Amazon S3 REST API specification.

6.14.1. Response Elements

  • Status

  • VersioningConfiguration

6.15. GET Bucket website

For the Amazon S3 "GET Bucket website" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Bucket website in the Amazon S3 REST API specification.

6.15.1. Response Elements

The response XML includes the same elements that were uploaded when the bucket was configured as a website.

6.16. HEAD Bucket

For the Amazon S3 "HEAD Bucket" operation, the Vault system supports the S3 common request headers and common response headers. For operation usage information see HEAD Bucket in the Amazon S3 REST API specification.

6.17. List Multipart Uploads

For the Amazon S3 "List Multipart Uploads" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see List Multipart Uploads in the Amazon S3 REST API specification.

6.17.1. Request Parameters

  • delimiter

  • encoding-type

  • max-uploads

  • key-marker

  • prefix

  • upload-id-marker

6.17.2. Response Elements

  • ListMultipartUploadsResult

  • Bucket

  • KeyMarker

  • UploadIdMarker

  • NextKeyMarker

  • NextUploadIdMarker

  • Encoding-Type

  • MaxUploads

  • IsTruncated

  • Upload

  • Key

  • UploadId

  • Initiator

  • ID

  • DisplayName

  • Owner

  • StorageClass

  • Initiated

  • ListMultipartUploadsResult.Prefix

  • Delimiter

  • CommonPrefixes

  • CommonPrefixes.Prefix

6.18. PUT Bucket

For the Amazon S3 "PUT Bucket" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Bucket in the Amazon S3 REST API specification.

6.18.1. Request Headers

  • x-amz-acl

  • x-amz-grant-read

  • x-amz-grant-write

  • x-amz-grant-read-acp

  • x-amz-grant-write-acp

  • x-amz-grant-full-control

6.18.2. Request Elements

  • CreateBucketConfiguration

  • LocationConstraint

Note The Vault system enforces the same bucket naming restrictions as does Amazon S3.

6.19. PUT Bucket acl

For the Amazon S3 "PUT Bucket acl" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Bucket acl in the Amazon S3 REST API specification.

6.19.1. Request Headers

  • x-amz-acl

  • x-amz-grant-read

  • x-amz-grant-write

  • x-amz-grant-read-acp

  • x-amz-grant-write-acp

  • x-amz-grant-full-control

6.19.2. Request Elements

  • AccessControlList

  • AccessControlPolicy

  • DisplayName

  • Grant

  • Grantee

  • ID

  • Owner

  • Permission

6.20. PUT Bucket cors

For the Amazon S3 "PUT Bucket cors" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Bucket cors in the Amazon S3 REST API specification.

6.20.1. Request Headers

  • Content-MD5

6.20.2. Request Elements

  • CORSConfiguration

  • CORSRule

  • ID

  • AllowedMethod

  • AllowedOrigin

  • AllowedHeader

  • MaxAgeSeconds

  • ExposeHeader

6.21. PUT Bucket lifecycle

For the Amazon S3 "PUT Bucket lifecycle" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Bucket lifecycle in the Amazon S3 REST API specification.

Note With the Vault system, only the bucket owner can create Lifecycle rules.

6.21.1. Request Headers

  • Content-MD5

Vault Extension to the S3 API

The Vault system supports the following Request Headers as extensions to the "PUT Bucket lifecycle" operation:

Parameter

Description

Required

x-gmt-tieringinfo

This extension header enables you to configure a bucket for schedule-based automatic transitioning (also known as "auto-tiering") of objects from Vault storage to Amazon S3 storage or Amazon Glacier storage. You can also auto-tier objects from one Vault region to another, or to a third party Vault system.

The x-gmt-tieringinfo header is formatted as follows:

x-gmt-tieringinfo: url-encode(S3/S3GLACIER|EndPoint:url-encode(s3-endpoint),
[Action:stream/nostream/redirect])
  • S3 or S3GLACIER — Specify S3 if you want to transition the objects to Amazon S3 storage, a different Vault service region, or a third party Vault service. Specify S3GLACIER if you want to transition the objects to Amazon Glacier. See example x-gmt-tieringinfo headers further below in this table.

  • EndPoint — Endpoint for the transition:

    • For transitioning to Amazon S3 or Glacier, specify an Amazon S3 endpoint suitable for your location (for example: s3-us-west-1.amazonaws.com). Note that even if the destination is Glacier, you will specify an Amazon S3 endpoint, not a Glacier endpoint. (If you are tiering objects to Glacier, the Vault system will first transition the objects to your specified Amazon S3 endpoint and then they will be immediately transitioned to the corresponding Glacier location.)

      Note By default auto-tiering to Amazon uses a special Amazon account that Nicman sets up for this purpose. If instead you want to auto-tier to an existing Amazon account, you must provide the Vault system with the S3 access credentials for the account. You can do this by using the Vault Admin API’s POST Amazon Tiering Credentials method. The CMC also supports supplying S3 access credentials to use for auto-tiering to an existing account.
    • For transitioning to a different Vault service region, or to a third party Vault service, you must specify a Vault service endpoint that administrators of your Vault service have added to the Vault S3 configuration file tiering-regions.xml. If you specify an endpoint that is not in this file, your PUT Bucket Lifecycle request will be rejected. Also, the destination Vault domain must be resolvable in your DNS configuration.

    • As indicated in the x-gmt-tieringinfo format specification above, you must use nested URL encoding. First URL encode the Endpoint value (the endpoint itself), and then URL encode the whole x-gmt-tieringinfo value.

  • [Action:] — This option specifies how the Vault system will handle GET requests for tiered objects. This option is only applicable for objects that have been transitioned to Amazon S3, a different Vault region, or a third party Vault Service. The supported methods for handling GETs are:

    • stream — The Vault system GETs the object from the tiered storage system (whether Amazon S3 or Nicman Vault) and streams it through to the client. This is the default method which will be used if you do not specify the Action: option.

    • nostream — Streaming of tiered objects is not allowed. Instead, the GET is rejected and clients will need to execute a POST Object Restore request in order to temporarily restore a copy of the object in local Vault storage.

    • redirect — When a user does a GET on a tiered object the response from the Vault system will be an HTTP 307 with a signed redirect URL to the object’s location in the tiered storage system.

      Note For objects tiered to Glacier, using the POST Object Restore operation is the only supported object retrieval method. Streaming and redirects are not supported.
# Example 1 (before URL encoding) - Tiering to Amazon S3

x-gmt-tieringinfo: S3|EndPoint:http://s3.amazonaws.com.

# Example 2 (before URL encoding) - Tiering to a different Vault region

x-gmt-tieringinfo: S3|EndPoint:http://s3-west.my-organization.com.

# Example 3 (before URL encoding) - Tiering to a third party
# Vault service

x-gmt-tieringinfo: S3|EndPoint:http://s3.other-organization.com.

# Example 4 (before URL encoding) - Tiering to Glacier

x-gmt-tieringinfo: S3GLACIER|EndPoint:http://s3.amazonaws.com.

# URL encoding of Example 4

x-gmt-tieringinfo: S3GLACIER%7CEndPoint%3Ahttp%253A%252F%252Fs3.amazonaws.com.

No

x-gmt-compare

If you include this extension header in your "PUT Bucket lifecycle" request and set the header value to "LAT", then in lifecycle rules that you configure with the "Days" comparator the rule will be implemented as number of days since the object’s Last Access Time.

If you do not use this extension header, or if you include the header but assign it no value or any value other than "LAT", then "Days" based lifecycle rules will be implemented as number of days since the object’s creation (the default Amazon S3 behavior).

You can use this header to create:

  • Last Access Time based auto-tiering rules (use this header and also the x-gmt-tierinfo header).

  • Last Access Time based expiration rules (use this header but not the x-gmt-tierinfo header).

Note

An object’s Last Access Time is updated if the object is accessed either for retrieval (GET or HEAD) or modification (PUT/POST/Copy).

If an object is created and then never accessed, its Last Access Time will be its Creation Time.

No

Note If you are using the x-gmt-tieringinfo request header, then for the request element StorageClass you must specify "GLACIER". This is true regardless of whether you want to transition the objects to Amazon Glacier, Amazon S3, a different Vault service region, or a third party Vault service.

A sample PUT Bucket Lifecycle request/response pair is below. This rule transitions objects in the user’s Vault S3 storage bucket to Amazon S3 90 days after Last Access Time. Note that the StorageClass element specifies GLACIER even though the tiering target is actually Amazon S3.

# Request

PUT /?lifecycle HTTP/1.1.
Host: bucket1.nicmanlab.com:80.
Accept-Encoding: identity.
Content-Length: 216.
User-Agent: Boto/2.24.0 Python/2.6.6 Linux/2.6.32-358.23.2.el6.x86_64.
x-gmt-tieringinfo: S3%7CEndPoint%3Ahttp%253A%252F%252Fs3.amazonaws.com.
x-gmt-compare: LAT
Date: Sun, 16 Nov 2014 17:54:16 GMT.
Content-MD5: Nip5xNP0P41djj608bRHNQ==.
Content-Type: text/xml.
Authorization: AWS a-key:NfPRnsSbTcxBZ2vN2MX4ZsArJAQ=.
.

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>Transition to Amazon S3</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Transition>
      <StorageClass>GLACIER</StorageClass>
      <Days>90</Days>
    </Transition>
  </Rule>
</LifecycleConfiguration>


# Response

HTTP/1.1 200 OK.
Date: Sun, 16 Nov 2014 17:54:16 GMT.
x-amz-request-id: AF5C7C2098C511E3.
x-gmt-usage: 0,1,623,89,0.
Content-Length: 0.
Server: Nicmanlab.

A second sample PUT Bucket Lifecycle request/response pair is below. This rule transitions all objects in the user’s Vault S3 storage bucket to Amazon Glacier one year after object creation, and then expires (deletes) the objects five years after object creation. Note that the EndPoint is an Amazon S3 endpoint even though the ultimate tiering target is Glacier.

# Request

PUT /?lifecycle HTTP/1.1.
Host: bucket1.nicmanlab.com:80.
Accept-Encoding: identity.
Content-Length: 235.
User-Agent: Boto/2.24.0 Python/2.6.6 Linux/2.6.32-358.23.2.el6.x86_64.
x-gmt-tieringinfo: S3GLACIER%7CEndPoint%3Ahttp%253A%252F%252Fs3.amazonaws.com.
Date: Tue, 18 Feb 2014 17:54:16 GMT.
Content-MD5: Nip5xNP0P41djj608bRQHN==.
Content-Type: text/xml.
Authorization: AWS a-key:NfPRnsSbTcxBZ2vN2MX4ZsArJAQ=.
.

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
  <Rule>
    <ID>Transition to Glacier and later delete</ID>
    <Prefix></Prefix>
    <Status>Enabled</Status>
    <Transition>
      <StorageClass>GLACIER</StorageClass>
      <Days>365</Days>
    </Transition>
    <Expiration>
      <Days>1825</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>


# Response

HTTP/1.1 200 OK.
Date: Tue, 18 Feb 2014 17:58:16 GMT.
x-amz-request-id: AF5C7C2098C522F4.
x-gmt-usage: 0,1,623,89,0.
Content-Length: 0.
Server: nicmanlab.

6.21.2. Request Elements

  • Date

  • Days

  • Expiration

  • ID

  • LifecycleConfiguration

  • Prefix

  • Rule

  • Status

  • StorageClass

    Note If you are using the Vault extension request header x-gmt-tieringinfo, then for the request element StorageClass you must specify "GLACIER". This is true regardless of whether you want to transition the objects to Amazon Glacier, Amazon S3, a different Vault service region, or a third party Vault service.
  • Transition

6.22. PUT Bucket policy

For the Amazon S3 "PUT Bucket policy" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Bucket policy in the Amazon S3 REST API specification. For policy construction guidance see also the Amazon documentation on Using Bucket Policies, but note that the Vault system supports only the policy types indicated below.

6.22.1. Request Elements

The body is a JSON string containing the policy contents containing the policy statements.

The Vault system supports only these bucket policy types:

Restricting Access to a Specific HTTP Referrer

The only accepted format is the below that allows GetObject on the bucket from only the specified referrer URIs.

{
  "Version":"2012-10-17",
  "Id":"http referer policy example",
  "Statement":[
    {
      "Sid":"Allow get requests originated from URI-1 and URI-2",
      "Effect":"Allow",
      "Principal":"*",
      "Action":"s3:GetObject",
      "Resource":"arn:aws:s3:::examplebucket/*",
      "Condition":{
            "StringLike":{
               "aws:Referer":["URI-1"]
               },
            "StringLike":{
               "aws:Referer":["URI-2"]
               }
            }
         }
      }
   ]
}
  • Multiple "StringLike" conditions can be specified.

  • URI value (e.g., URI-1 and URI-2) is compared to HTTP Referer header with case-insensitive matching and multi-character wildcard (*) and single-character wildcard (?).

Restricting Access to Specific IP Addresses

The Vault system supports restricting bucket access to specific source IP addresses, by using the "IpAddress" and/or "NotIpAddress" conditions and the "aws:SourceIp" condition key. The example below allows authenticated users from source address range 54.240.143.* to perform any S3 action — except for users from origin IP address 54.240.143.188, which is forbidden access.

{
    "Version": "2012-10-17",
    "Id": "S3PolicyId1",
    "Statement": [
        {
            "Sid": "IPAllow",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::examplebucket/*",
            "Condition" : {
                "IpAddress" : {
                    "aws:SourceIp": "54.240.143.0/24"
                },
                "NotIpAddress" : {
                    "aws:SourceIp": "54.240.143.188/32"
                }
            }
        }
    ]
}
Policy for Server-Side Encryption

The Vault systems supports bucket policies that mandate server-side encryption (so that object upload requests are rejected if they omit the server-side encryption request header) or that forbid server-side encryption (so that object upload requests are rejected if they include the server-side encryption request header).

For example, the policy below requires all PUT Object requests to include the encryption request header:

{
   "Version":"2012-10-17",
   "Id":"PutObjPolicy",
   "Statement":[{
         "Sid":"DenyUnEncryptedObjectUploads",
         "Effect":"Deny",
         "Principal":"*"
         "Action":"s3:PutObject",
         "Resource":"arn:aws:s3:::YourBucket/*",
         "Condition":{
            "StringNotEquals":{
               "s3:x-amz-server-side-encryption":"AES256"
            }
         }
      }
   ]
}
Policy for Public Access to Buckets Configured as Websites

If you have configured a bucket as a static website (using PUT Bucket Website), you can establish a bucket policy that allows public access to the website:

{
  "Version":"2012-10-17",
  "Statement":[{
      "Sid":"PublicReadForGetBucketObjects",
      "Effect":"Allow",
      "Principal": "*"
      "Action":["s3:GetObject"],
      "Resource":["arn:aws:s3:::example-bucket/*"
      ]
    }
  ]
}

For further information, see the Amazon documentation on Setting Up a Website.

6.22.2. Response Elements

PUT response elements return whether the operation succeeded or not.

6.23. PUT Bucket logging

For the Amazon S3 "PUT Bucket logging" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Bucket logging in the Amazon S3 REST API specification.

Note If you are supporting bucket logging in your service, and if you use a load balancer in front of your S3 Service nodes, you should configure your S3 Service to support the HTTP X-Forwarded-For header. This will enable bucket logs to record the true originating IP address of S3 requests, rather than the load balancer IP address. By default the S3 Service does not support the X-Forwarded-For header. You can enable support for this header using the system configuration file s3.xml.erb.

6.23.1. Request Elements

  • BucketLoggingStatus

  • EmailAddress

  • Grant

  • Grantee

  • LoggingEnabled

  • Permission

  • TargetBucket

  • TargetGrants

  • TargetPrefix

6.24. PUT Bucket versioning

For the Amazon S3 "PUT Bucket versioning" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Bucket versioning in the Amazon S3 REST API specification.

6.24.1. Request Elements

  • Status

  • VersioningConfiguration

6.25. PUT Bucket website

For the Amazon S3 "PUT Bucket website" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Bucket website in the Amazon S3 REST API specification.

6.25.1. Request Elements

  • WebsiteConfiguration

  • RedirectAllRequestsTo

  • HostName

  • Protocol

  • WebsiteConfiguration

  • IndexDocument

  • ErrorDocument

6.26. DELETE Bucket Storage Type (Vault Extension)

6.26.1. Description

This operation is a Vault extension to the Amazon S3 API. The operation is for deleting a bucket storage type configuration, subsequent to the bucket having been assigned a storage type configuration with the PUT Bucket Storage Type operation. If a bucket storage configuration is deleted, the bucket returns to using the system default storage type configuration.

For more information on this Vault feature, see PUT Bucket Storage Type (Vault Extension).

6.26.2. Requests

Syntax
DELETE /?hyperstore HTTP/1.1
Host: <bucketname>.<s3.domain.com>
Content-Length: <length>
Date: <date>
Authorization: <authorization string>
Request Parameters

This operation does not use request parameters.

Request Headers

This operation uses only Common Request Headers.

Request Elements

This operation does not use request elements.

6.26.3. Responses

Response Headers

This operation uses only Common Response Headers.

Response Elements

This operation does not return response elements.

Special Errors

This operation does not return special errors.

6.26.4. Example

The sample request/response pair below shows how to delete an existing storage type configuration for a bucket. Following this operation, the storage type for this bucket will return to the system default.

# Request

DELETE /?hyperstore HTTP/1.1.
Host: buser1.s3.nicmanlab.com.
Content-Length: 0.
Date: Wed, 15 Jan 2014 22:11:40 GMT.
Authorization: AWS 0089edbee087309aabfb:EwssK/8JOnkEg7Vw9vfRtUlNBwk=.

# Response

HTTP/1.1 204 No Content.
Date: Wed, 15 Jan 2014 22:11:40 GMT.
x-amz-request-id: 2AC2EB07E3211E3.
Server: nicmanlab.

6.27. GET Bucket Storage Type (Vault Extension)

6.27.1. Description

This operation is a Vault extension to the Amazon S3 API. The operation is for retrieving a bucket storage type configuration, subsequent to the bucket having been assigned a storage type configuration with the PUT Bucket Storage Type operation.

For more information on this Vault feature, see PUT Bucket Storage Type (Vault Extension).

6.27.2. Requests

Syntax
GET /?hyperstore HTTP/1.1
Host: <bucketname>.<s3.domain.com>
Content-Length: <length>
Date: <date>
Authorization: <authorization string>
Request Parameters

This operation does not use request parameters.

Request Headers

This operation uses only Common Request Headers.

Request Elements

This operation does not use request elements.

6.27.3. Responses

Response Headers

This operation uses only Common Response Headers.

Response Elements

Name

Description

Required

HSConfiguration

The container for the bucket’s storage type configuration settings.

Yes

LargeStorage

Specifies how to store S3 objects that are larger than the threshold. Options are:

  • HSFS — Store objects in the Vault File System and protect them by using replication. The number of replicas is set by system configuration (region.csv:userdata_keyspace_strategy_options).

  • EC — Use erasure coding to store and protect objects.

Yes

Threshold

Object size threshold in number of bytes. Objects larger than this will be stored in the manner specified by LargeStorage. Objects this size or smaller will be stored in Cassandra and protected by replication. The number of replicas is set by system configuration (region.csv:userdata_keyspace_strategy_options).

Yes

Special Errors

This operation does not return special errors.

6.27.4. Example

The sample request/response pair below shows how to retrieve an existing storage type configuration for a bucket.

# Request

GET /?hyperstore HTTP/1.1.
Host: buser1.s3.nicmanlab.com.
Content-Length: 0.
Date: Wed, 15 Jan 2014 22:11:40 GMT.
Authorization: AWS 0089edbee087309aabfb:s7KswUvssgK9YJz8V3L7xfbpyWU=.

# Response

HTTP/1.1 200 OK.
Date: Wed, 15 Jan 2014 22:11:40 GMT.
x-amz-request-id: 2A63B407E3211E3.
Content-Type: application/xml;charset=UTF-8.
Content-Length: 103.
Server: nicmanlab.

<?xml version="1.0" encoding="UTF-8"?>
<HSConfiguration>
<LargeStorage>HSFS</LargeStorage>
<Threshold>20</Threshold>
</HSConfiguration>

6.28. PUT Bucket Storage Type (Vault Extension)

6.28.1. Description

This operation is a Vault extension to the Amazon S3 API. The operation enables S3 clients to configure on a per-bucket basis how to store and protect S3 objects that are larger than a specified size threshold. The options are:

  • Store such objects in the HyperStore File System, where they are protected by replication.

  • Use erasure coding to store and protect such objects.

This S3 API extension also enables clients to specify the size threshold. S3 objects larger than this threshold will be stored according to the selected storage type. Objects at or below this size threshold will be stored in the Cassandra database and protected by replication.

Note

Support for this S3 API extension can be enabled or disabled via the system configuration property mts.properties: vault.s3.hsconfiguration.enabled. It is disabled by default. If disabled, requests to PUT, GET, or DELETE a bucket storage type will be rejected with an HTTP 403 error response. When the API extension is disabled, handling of large S3 objects is determined by system configuration (common.csv:hyperstore_size_threshold and common.csv:hyperstore_large_storage).

If this S3 API extension is enabled, then support for the x-gmt-hyperstore extension header to PUT Object, POST Object, and Initiate Multipart Upload is also enabled. With this extension header, S3 clients can override a bucket-level storage type configuration on a per-object basis. For example, a PUT Object request with the x-gmt-hyperstore header could direct the object to the Vault File System even if the object’s parent bucket is configured for erasure coding. Therefore bucket-level configuration is best regarded as setting a default for how to store and protect large objects in the bucket, with the caveat that the default may be overridden on a per-object basis.

In the case of large S3 objects for which no storage type configuration has been specified either at the per-object level or the per-bucket level, handling is determined by system configuration (based on the settings mentioned in the first part of this Note).

6.28.2. Requests

Syntax
PUT /?hyperstore HTTP/1.1
Host: <bucketname>.<s3.domain.com>
Content-Length: <length>
Date: <date>
Authorization: <authorization string>

<Bucket storage type configuration in the request body>
Request Parameters

This operation does not use request parameters.

Request Headers

This operation uses only Common Request Headers.

Request Elements

Name

Description

Required

HSConfiguration

The container for the bucket’s storage type configuration settings.

Yes

LargeStorage

Specifies how to store S3 objects that are larger than the threshold. Options are:

  • HSFS — Store objects in the Vault File System and protect them by using replication. The number of replicas is set by system configuration (region.csv:userdata_keyspace_strategy_options).

  • EC — Use erasure coding to store and protect objects.

Yes

Threshold

Object size threshold in number of bytes. Objects larger than this will be stored in the manner specified by LargeStorage. Objects this size or smaller will be stored in Cassandra and protected by replication. The number of replicas is set by system configuration (region.csv:userdata_keyspace_strategy_options).

Yes

6.28.3. Responses

Response Headers

This operation uses only Common Response Headers.

Response Elements

This operation does not return response elements.

Special Errors

This operation does not return special errors.

6.28.4. Example

The sample request/response pair below shows how to PUT a bucket storage type configuration. The bucket name in this example is buser1. With the bucket storage type configuration in this example, all S3 objects larger than 20 bytes will be stored in the Vault File System.

# Request

PUT /?hyperstore HTTP/1.1
Host: buser1.s3.nicmanlab.com
Content-Length: 111
Date: Wed, 15 Jan 2014 22:11:40 GMT
Authorization: AWS 0089edbee087309aabfb:dsDauMNvstO4cZ4TGeXXXXoLNnQ=

<?xml version="1.0" encoding="UTF-8"?>
<HSConfiguration xmlns="http://s3.nicmanlab.com/doc/2013-10-01/">
<LargeStorage>HSFS</LargeStorage>
<Threshold>20</Threshold>
</HSConfiguration>

# Response

HTTP/1.1 200 OK.
Date: Wed, 15 Jan 2014 22:11:40 GMT.
x-amz-request-id: 27A49407E3211E3.
Content-Length: 0.
Server: nicmanlab.

6.29. GET Bucket Virtualization (Vault Extension)

6.29.1. Description

This operation is a Vault extension to the Amazon S3 API. The operation is for retrieving the virtualization status of a bucket.

For more information on this Vault feature, see PUT Bucket Virtualization (Vault Extension).

6.29.2. Requests

Syntax
GET /?virtualization HTTP/1.1
Host: <bucketname>.<s3.domain.com>
Content-Length: <length>
Date: <date>
Authorization: <authorization string>
Request Parameters

This operation does not use request parameters.

Request Headers

This operation uses only Common Request Headers.

Request Elements

This operation does not use request elements.

6.29.3. Responses

Response Headers

This operation uses only Common Response Headers.

Response Elements

Name

Description

Required

VirtualizationConfiguration

The container for the bucket’s virtualization configuration.

Yes

Status

The bucket’s virtualization status. Options are:

  • Enabled — The bucket is configured as a virtual bucket.

  • Disabled — The bucket is not configured as a virtual bucket. If a bucket that was once enabled for virtualization is subsequently disabled, the objects that are in regions other than the bucket’s home region remain in those other regions and continue to be retrievable via GET Object requests. After virtualization is disabled, new objects that are PUT to the bucket will all be stored in the bucket’s home region.

Yes

Special Errors

This operation does not return special errors.

6.29.4. Example

The sample request/response pair below shows how to retrieve a bucket’s virtualization status. In the example, the bucket name is bucket1, and the response shows that the bucket is configured for virtualization.

# Request

GET /?virtualization HTTP/1.1
Host: bucket1.s3.nicmanlab.com
Date: Mon, 06 Aug 2012 21:34:29 GMT
Content-Length: 0
Authorization: AWS 51363971e136bd3c1b84:pAGPZVUiIgxhxEXxptDm+iqUmtw=

# Response

HTTP/1.1 200 OK
Date: Mon, 06 Aug 2012 21:37:57 GMT
x-amz-request-id: FD1373E0E00E11E1
Content-Type: application/xml;charset=UTF-8
Content-Length: 121

<?xml version="1.0" encoding="UTF-8"?>
<VirtualizationConfiguration>
<Status>Enabled</Status>
</VirtualizationConfiguration>

6.30. PUT Bucket Virtualization (Vault Extension)

6.30.1. Description

This operation is a Vault extension to the Amazon S3 API. The operation enables an existing bucket to be configured as a "virtual bucket". A virtual bucket is a bucket of unlimited size for which object storage spans multiple Vault service regions. The virtual bucket feature is applicable only for a multi-region Vault deployment. Its purpose is to accommodate buckets with larger capacities than service providers may wish to allow in a single region.

When a bucket is virtualized, objects PUT into that bucket may be stored in the same region in which the bucket was created, or in any other region in the Vault service deployment. The system’s determination as to which region to store the object into is based on a consistent hashing scheme. Each region is assigned a token (forming a token ring). When the S3 Server in the region in which the bucket was created subsequently receives PUT Object requests for the bucket, it assigns each object a token (derived from a hash of the bucket name and object name) and then transmits the object to the region whose token range encompasses the object’s token (which may be the local region or any of the other regions).

Note Per-region tokens are configured by system configuration setting region.csv:virtual_bucket_token.

Subsequent requests to retrieve (or delete) an object stored in a virtual bucket are handled by the S3 service in the region in which the bucket was originally created. The S3 service routes the request to the correct region. This action is invisible to the client. After the correct region returns a response to the S3 service in the region that’s handling the request, the S3 service returns a response to the client.

Regardless of which regions a virtualized bucket’s objects are stored in, all usage data for the bucket (for purposes of QoS enforcement and billing) is tracked at the region in which the bucket was originally created.

Note Virtual bucket requests sent to other regions are not counted toward bucket logging.

6.30.2. Requests

Syntax
PUT /?virtualization HTTP/1.1
Host: <bucketname>.<s3.domain.com>
Content-Length: <length>
Date: <date>
Authorization: <authorization string>

<Bucket virtualization configuration in the request body>
Note Do not apply virtualization to a bucket that has an underscore in its name. You will not be able to PUT objects into a virtualized bucket that has an underscore in its name.
Request Parameters

This operation does not use request parameters.

Request Headers

This operation uses only Common Request Headers.

Request Elements

Name

Description

Required

VirtualizationConfiguration

The container for the bucket’s virtualization configuration.

Yes

Status

The bucket’s virtualization status. Options are:

  • Enabled — The bucket is configured as a virtual bucket.

  • Disabled — The bucket is not configured as a virtual bucket. If a bucket that was once enabled for virtualization is subsequently disabled, the objects that are in regions other than the bucket’s home region remain in those other regions and continue to be retrievable via GET Object requests. After virtualization is disabled, new objects that are PUT to the bucket will all be stored in the bucket’s home region.

Yes

6.30.3. Responses

Response Headers

This operation uses only Common Response Headers.

Response Elements

This operation does not return response elements.

Special Errors

This operation does not return special errors.

6.30.4. Example

The request below illustrates how to enable virtualization on a bucket named "bucket1". Note that in the request object the Status attribute is set to Enabled.

PUT /?virtualization HTTP/1.1
Host: bucket1.s3.nicmanlab.com
Content-Length: 195
Date: Mon, 06 Aug 2012 21:32:58 GMT
Authorization: AWS 51363971e136bd3c1b84:a3fGaBkCyg1ZQym3czNPicbF9Uo=
User-Agent: Boto/2.3.0 (linux2)

<?xml version="1.0" encoding="UTF-8"?>
<VirtualizationConfiguration xmlns="http://s3.nicmanlab.com/2013-10-01/">
<Status>Enabled</Status>
</VirtualizationConfiguration>

7. Operations on Objects

From the "Operations on Objects" section of the Amazon S3 REST API, the Vault system supports the operations listed below. If an operation is not listed here, the Vault system does not support it. For details of Vault support for specific operations — such as which parameters and headers are supported — click on the links.

7.1. DELETE Object

For the Amazon S3 "DELETE Object" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see DELETE Object in the Amazon S3 REST API specification.

7.1.1. Response Headers

  • x-amz-delete-marker

  • x-amz-version-id

7.2. Delete Multiple Objects

For the Amazon S3 "Delete Multiple Objects" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see Delete Multiple Objects in the Amazon S3 REST API specification.

7.2.1. Request Headers

  • Content-MD5

  • Content-Length

7.2.2. Request Elements

  • Delete

  • Quiet

  • Object

  • Key

  • VersionId

7.2.3. Response Elements

  • DeleteResult

  • Deleted

  • Key

  • VersionId

  • DeleteMarker

  • DeleteMarkerVersionId

  • Error

  • Key

  • VersionId

  • Code

  • Message

7.3. GET Object

For the Amazon S3 "GET Object" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Object in the Amazon S3 REST API specification.

7.3.1. Request Parameters

  • response-content-type

  • response-content-language

  • response-expires

  • response-cache-control

  • response-content-disposition

  • response-content-encoding

7.3.2. Request Headers

  • Range

  • If-Modified-Since

  • If-Unmodified-Since

  • If-Match

  • If-None-Match

7.3.3. Response Headers

  • x-amz-delete-marker

  • x-amz-expiration

  • x-amz-server-side-encryption

  • x-amz-restore

  • x-amz-version-id

  • x-amz-website-redirect-location

7.4. GET Object ACL

For the Amazon S3 "GET Object ACL" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see GET Object ACL in the Amazon S3 REST API specification.

7.4.1. Response Elements

  • AccessControlList

  • AccessControlPolicy

  • DisplayName

  • Grant

  • Grantee

  • ID

  • Owner

  • Permission

7.5. HEAD Object

For the Amazon S3 "HEAD Object" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see HEAD Object in the Amazon S3 REST API specification.

7.5.1. Request Headers

  • Range

  • If-Modified-Since

  • If-Unmodified-Since

  • If-Match

  • If-None-Match

7.5.2. Response Headers

  • x-amz-expiration

  • x-amz-meta-*

  • x-amz-restore

  • x-amz-server-side-encryption

  • x-amz-version-id

7.6. OPTIONS object

For the Amazon S3 "OPTIONS object" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see OPTIONS object in the Amazon S3 REST API specification.

7.6.1. Request Headers

  • Origin

  • Access-Control-Request-Method

  • Access-Control-Request-Headers

7.6.2. Response Headers

  • Access-Control-Allow-Origin

  • Access-Control-Max-Age

  • Access-Control-Allow-Methods

  • Access-Control-Allow-Headers

  • Access-Control-Expose-Headers

7.7. POST Object

For the Amazon S3 "POST Object" operation, the Vault system supports the S3 common response headers and also the operation-specific items listed below. If a form field, parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see POST Object in the Amazon S3 REST API specification.

7.7.1. Form Fields

  • AWSAccessKeyId

  • acl

  • Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires

  • file

  • key

  • policy

  • success_action_redirect, redirect

  • success_action_status

  • x-amz-storage-class (STANDARD only)

  • x-amz-meta-*

  • x-amz-website-redirect-location

  • x-amz-server-side-encryption

7.7.2. Request Header: Vault Extension to the S3 API

The Vault system supports the following request header as an extension to the "POST Object" operation:

Name

Description

Required

x-gmt-hyperstore

Clients can use this request header to specify the Vault storage type to apply to the object that’s being POSTed. Options are:

  • CASSANDRA — Store the object in the Cassandra database and protect the object by replicating it. The number of replicas is controlled by system configuration (region.csv:userdata_keyspace_strategy_options). CASSANDRA is not a valid option for "chunked" objects (objects larger than the system configuration setting mts.properties: cassandra.fs.max_chunk_size; the default is 10485760 bytes).

  • HSFS — Store the object in the Vault File System and protect the object by replicating it. The number of replicas is controlled by system configuration (region.csv: userdata_keyspace_strategy_options).

  • EC — Use erasure coding to store and protect the object.

No

7.7.3. Response Headers

  • x-amz-expiration

  • success_action_redirect, redirect

  • x-amz-server-side-encryption

  • x-amz-version-id

7.7.4. Response Elements

  • Bucket

  • ETag

  • Key

  • Location

7.8. POST Object restore

For the Amazon S3 "POST Object restore" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see POST Object restore in the Amazon S3 REST API specification.

7.8.1. Request Headers

  • Content-MD5

7.8.2. Request Elements

  • RestoreRequest

  • Days

7.9. PUT Object

For the Amazon S3 "PUT Object" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Object in the Amazon S3 REST API specification.

7.9.1. Request Headers

  • Cache-Control

  • Content-Disposition

  • Content-Encoding

  • Content-Length

  • Content-MD5

  • Content-Type

  • Expect

  • Expires

  • x-amz-meta-

  • x-amz-storage-class

  • x-amz-website-redirect-location

  • x-amz-acl

  • x-amz-grant-read

  • x-amz-grant-write

  • x-amz-grant-read-acp

  • x-amz-grant-write-acp

  • x-amz-grant-full-control

  • x-amz-server-side-encryption

Vault Extension to the S3 API

The Vault system supports the following Request Header as an extension to the "PUT Object" operation:

Name

Description

Required

x-gmt-hyperstore

Clients can use this header to specify the Vault storage type to apply to the object that’s being PUT. Options are:

  • CASSANDRA — Store the object in the Cassandra database and protect the object by replicating it. The number of replicas is controlled by system configuration (region.csv:userdata_keyspace_strategy_options). CASSANDRA is not a valid option for "chunked" objects (objects larger than the system configuration setting mts.properties:cassandra.fs.max_chunk_size; the default is 10485760 bytes).

  • HSFS — Store the object in the Vault File System and protect the object by replicating it. The number of replicas is controlled by system configuration (region.csv:userdata_keyspace_strategy_options).

  • EC — Use erasure coding to store and protect the object.

No

Vault Restrictions on Object Names

The following control characters cannot be used anywhere in an object name and will result in a 400 Bad Request response: 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A ("\n"), 0x0B, 0x0C, 0x0D ("\r"), 0x0E, 0x0F, 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E, 0x1F

Also unsupported are:

  • 0x09 ("\t") at the beginning of an object name

  • 0xBF (inverted question mark) at the end of an object name

Also, an object name may result in 400 Bad Request or be stored as a different name if the supplied object name:

  • Consists only of "."

  • Consists only of ".."

  • Contains a combination of "." and "/", or ".." and "/"

Examples of character sequences that will result in 400 Bad Request:

.

..

./

../

./.

./..

../.

../..

../a

../a/

a/../../b

Examples of character sequences that will be stored as a different name:

Supplied Object Name Stored As

./a

a

./a/

a/

a//b

a/b

a/./b

a/b

a/../b

b

a/.././b

b

7.9.2. Response Headers

  • x-amz-expiration

  • x-amz-server-side-encryption

  • x-amz-server-side-encryption-customer-algorithm

  • x-amz-version-id

7.10. PUT Object acl

For the Amazon S3 "PUT Object acl" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Object acl in the Amazon S3 REST API specification.

7.10.1. Request Headers

  • x-amz-acl

  • x-amz-grant-read

  • x-amz-grant-write

  • x-amz-grant-read-acp

  • x-amz-grant-write-acp

  • x-amz-grant-full-control

7.10.2. Request Elements

  • AccessControlList

  • AccessControlPolicy

  • DisplayName

  • Grant

  • Grantee

  • ID

  • Owner

  • Permission

7.10.3. Response Headers

  • x-amz-version-id

7.11. PUT Object - Copy

For the Amazon S3 "PUT Object - Copy" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see PUT Object - Copy in the Amazon S3 REST API specification.

7.11.1. Request Headers

  • x-amz-copy-source

  • x-amz-metadata-directive

  • x-amz-copy-source-if-match

  • x-amz-copy-source-if-none-match

  • x-amz-copy-source-if-unmodified-since

  • x-amz-copy-source-if-modified-since

  • x-amz-storage-class

  • x-amz-website-redirect-location

  • x-amz-server-side-encryption

  • x-amz-acl

  • x-amz-grant-read

  • x-amz-grant-write

  • x-amz-grant-read-acp

  • x-amz-grant-write-acp

  • x-amz-grant-full-control

7.11.2. Response Headers

  • x-amz-expiration

  • x-amz-copy-source-version-id

  • x-amz-server-side-encryption

  • x-amz-version-id

7.11.3. Response Elements

  • CopyObjectResult

  • ETag

  • LastModified

7.12. Initiate Multipart Upload

For the Amazon S3 "Initiate Multipart Upload" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see Initiate Multipart Upload in the Amazon S3 REST API specification.

7.12.1. Request Headers

  • Cache-Control

  • Content-Disposition

  • Content-Encoding

  • Content-Type

  • Expires

  • x-amz-meta-

  • x-amz-storage-class

  • x-amz-website-redirect-location

  • x-amz-acl

  • x-amz-grant-read

  • x-amz-grant-write

  • x-amz-grant-read-acp

  • x-amz-grant-write-acp

  • x-amz-grant-full-control

  • x-amz-server-side-encryption

Vault Extension to the S3 API

The Vault system supports the following Request Header as an extension to the "Initiate Multipart Upload" operation:

Name

Description

Required

x-gmt-hyperstore

Clients can use this header to specify the Vault storage type to apply to the object that’s being uploaded. Options are:

  • HSFS — Store the object in the Vault File System and protect the object by replicating it. The number of replicas is controlled by system configuration (region.csv:userdata_keyspace_strategy_options).

  • EC — Use erasure coding to store and protect the object.

Note When the x-gmt-hyperstore header is used with POST Object or PUT Object operations it supports a third option, CASSANDRA. However, CASSANDRA is not a valid option for multipart uploads.

No

7.12.2. Response Headers

  • x-amz-server-side-encryption

7.12.3. Response Elements

  • InitiateMultipartUploadResult

  • Bucket

  • Key

  • UploadId

7.13. Upload Part

For the Amazon S3 "Upload Part" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see Upload Part in the Amazon S3 REST API specification.

7.13.1. Request Headers

  • Content-Length

  • Content-MD5

  • Expect

  • x-amz-server-side-encryption

7.13.2. Response Headers

  • x-amz-server-side-encryption

7.13.3. Special Errors

  • NoSuchUpload

7.14. Upload Part - Copy

For the Amazon S3 "Upload Part - Copy" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see Upload Part - Copy in the Amazon S3 REST API specification.

7.14.1. Request Headers

  • x-amz-copy-source

  • x-amz-copy-source-range

  • x-amz-copy-source-if-match

  • x-amz-copy-source-if-none-match

  • x-amz-copy-source-if-unmodified-since

  • x-amz-copy-source-if-modified-since

7.14.2. Response Headers

  • x-amz-copy-source-version-id

  • x-amz-server-side-encryption

7.14.3. Response Elements

  • CopyPartResult

  • ETag

  • LastModified

7.14.4. Special Errors

  • NoSuchUpload

  • InvalidRequest

7.15. Complete Multipart Upload

For the Amazon S3 "Complete Multipart Upload" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see Complete Multipart Upload in the Amazon S3 REST API specification.

7.15.1. Request Elements

  • CompleteMultipartUpload

  • Part

  • PartNumber

  • ETag

7.15.2. Response Headers

  • x-amz-expiration

  • x-amz-server-side-encryption

  • x-amz-version-id

7.15.3. Response Elements

  • CompleteMultipartUploadResult

  • Location

  • Bucket

  • Key

  • ETag

7.15.4. Special Errors

  • InvalidPart

  • InvalidPartOrder

  • NoSuchUpload

7.16. Abort Multipart Upload

For the Amazon S3 "Abort Multipart Upload" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see Abort Multipart Upload in the Amazon S3 REST API specification.

7.16.1. Special Errors

  • NoSuchUpload

7.17. List Parts

For the Amazon S3 "List Parts" operation, the Vault system supports the S3 common request headers and common response headers and also the operation-specific items listed below. If a parameter, header, element, or special error from the Amazon S3 specification for this operation is not listed below, the Vault system does not support it.

For operation usage information and for descriptions of request and response items, see List Parts in the Amazon S3 REST API specification.

7.17.1. Request Parameters

  • encoding-type

  • uploadId

  • max-parts

  • part-number-marker

7.17.2. Response Elements

  • ListPartsResult

  • Bucket

  • Encoding-Type

  • Key

  • UploadId

  • Initiator

  • ID

  • DisplayName

  • Owner

  • StorageClass

  • PartNumberMarker

  • NextPartNumberMarker

  • MaxParts

  • IsTruncated

  • Part

  • PartNumber

  • LastModified

  • ETag

  • Size

8. Access Control List (ACL)

For the Amazon S3 "Access Control List (ACL)" functionality, the Vault system supports the items listed below. If a grantee group, permission type, or canned ACL type from the Amazon S3 documentation is not listed below, the Vault system does not support it.

For ACL usage information and for descriptions of ACL items, see Access Control List (ACL) Overview in the Amazon S3 documentation.

8.1. Amazon S3 Predefined Groups

  • Authenticated users group

  • All users group

  • Log delivery group

8.2. Permission Types

  • READ

  • WRITE

  • READ_ACP

  • WRITE_ACP

  • FULL_CONTROL

8.3. Canned ACL

  • private

  • public-read

  • public-read-write

  • authenticated-read

  • bucket-owner-read

  • bucket-owner-full-control

8.3.1. Vault Extension to the S3 API

The Vault system supports these additional canned ACLs:

Canned ACL

Applies to

Permissions added to ACL

group-read

Bucket and object

Owner gets FULL_CONTROL. All other members of the owner’s Vault service user group get READ access.

group-read-write

Bucket and object

Owner gets FULL_CONTROL. All other members of the owner’s Vault service user group get READ and WRITE access.

Note To grant access to groups other than the requester’s own group, you cannot use canned ACLs. Instead, when using standard Amazon S3 methods for assigning privileges to a grantee (via request headers or request body), specify "<groupID>|" as the grantee. The "<groupID>|" format (with vertical bar) indicates that the grantee is a group — for example, "Group5|".
Note When access privileges have through separate requests been granted to a group and to a specific member of the group, the user gets the broader of the privilege grants. For example, if Group5 is granted read-write privileges and a specific user within Group5 is separately granted read privileges, the user gets read-write privileges.

9. Vault Developer Topics

9.1. General Guidance on Developing S3 Applications for the Vault Service

In nearly every way, developing a client application for the Nicman Vault storage service is the same as developing a client application for Amazon S3. Consequently, when designing and building S3 applications for the Vault service you can leverage the wealth of resources available to Amazon S3 developers.

The best place to turn for resources for developing Amazon S3 and Nicman Vault S3 applications is the Amazon S3 web site. Through that site, Amazon Web Services (AWS) Developer Centers are available for a variety of development technologies:

AWS Developer Centers include SDKs, community libraries, "Getting Started" guides, and tips and tricks.

Another good Amazon resource is the archive of Articles & Tutorials. The archive includes general articles such as "Best Practices for Using Amazon S3" as well as articles and tutorials relating to specific development technologies.

Yet another helpful Amazon resource is the archive of Sample Code & Libraries.

9.1.1. What’s Distinct About Developing for the Vault Service

In practice, the main differences between developing for developing for the Nicman Vault service and developing for Amazon S3 are:

  • As detailed in this document, the Vault service supports the great majority of but not the entire Amazon S3 API.

  • Also as detailed in this document, the Vault service supports a small number of extensions to the Amazon S3 API.

  • Vault client applications must use the Nicman Vault service endpoint rather than the Amazon S3 service endpoint.

  • You will need to use either the Vault Management Console or the Nicman Vault Administration API to create and manage service user accounts.

9.2. Implementing Single Sign-On for the CMC

To enable integration between a portal and the Vault Management Console (CMC), the Nicman Vault system employs one-way hash based Single Sign-On (SSO) solution. It allows for cross-domain sign-ons from the portal to CMC.

User provisioning is beyond the scope of the provided SSO solution. The Vault provides an Admin API for user provisioning but the implementation of user mapping is left to the portal application integrating with CMC.

Note

The CMC’s SSO solution has been redesigned in the Vault version 5.0

The following changes have been made.

  • The SSO Secure URL (ssosecurelogin.htm) now directly creates an authenticated CMC session instead of returning a CMCSSO cookie. Therefore, it is now possible to do cross-domain sign-ons from a portal to CMC. The portal and CMC no longer have to be on the same top level domain such as ".nicmanlab.com".

  • ssosecurelogin.htm also takes an optional query string redirect=RELATIVE_OR_ABSOLUTE_URL, which can be used to redirect the client to a CMC interior page upon successful sign-on.

  • The CMC logout URL (logout.htm) now takes an optional query string redirect=RELATIVE_OR_ABSOLUTE_URL, which can be used to redirect the client back to a portal page after signing out from the CMC.

Important

Backward compatibility and deprecated APIs

This redesigned SSO solution provides backward compatibility. If you already have working SSO from a portal to an earlier version of the CMC, it should remain working.

However, some of the SSO methods from earlier releases have been deprecated. Nicman recommends not using these methods, and in a future release support for them will be discontinued.

  • The method for having your portal application create a CMCSSO cookie has been deprecated. Use SSO secure login API (ssosecurelogin.htm) instead.

  • The method for having the CMC create a CMCSSO cookie using password (ssologin.htm) has been deprecated. Use SSO secure login API (ssosecurelogin.htm) instead.

  • The CMC SSO logout API (ssologout.htm) has been deprecated. Use CMC’s regular logout URL (logout.htm) instead.

9.2.1. How SSO for the CMC Works

Nicman Vault SSO is ideal for sites that already have an authentication model in place using a browser/login session and that want to incorporate the Vault Management Console into their web portal application.

The idea is that a portal application calculates an one-way hash (also known as a signature) based on Nicman Vault user identification, timestamp and the shared key. Then the user’s browser accesses ssosecurelogin.htm with the signature. The CMC checks for this signature to determine whether a user is authenticated or not. If the signature is found valid, access to the CMC from the client will skip the login page and take the user directly to a CMC interior page such as the Data Explorer page.

Important

To use the Nicman Vault SSO feature, in the CMC’s configuration file mts-ui.properties the following properties must be set to "true":

  • sso.enabled

    • This is set to false by default. Change it to true if you want to use SSO.

  • common.csv: cmc_web_secure

    • This is set to true by default. Leave it true if you want to use SSO.

Also in mts-ui.properties, if you enable SSO functionality (by setting sso.enabled to true), then for security reasons you should set sso.shared.key and sso.cookie.cipher.key to custom values. Do not use the default keys.

9.2.2. CMC SSO Secure Login Using One-Way Hash

The single sign-on with one-way hash method relies on a one-way hash of query string parameters (also known as a signature).

The following HTTP API, using a signature, prompts the CMC to create an authenticated session for the client that submitted the request:

https://<cmc_FQDN>:<cmc_port>/Vault/ssosecurelogin.htm?user=USERID&group=GROUPID
&timestamp=TIMESTAMP&signature=SIG&redirect=RELATIVE_OR_ABSOLUTE_URL
  • user: Nicman Vault userId of the user

  • group: Nicman Vault groupId of the group to which the user belongs

  • timestamp: Current Epoch time in milliseconds (eg. "1346881953440"). The timestamp is used to implement the configurable request expiration (mts-ui.properties: sso.tolerance.millis; expiration defaults to one hour).

  • signature: This is the URI encoding of the base64 representation of the calculated signature. For further information see below.

  • redirect: This optional parameter can be used to redirect the client to the given URL upon successful sign-in. It is typically set to a CMC interior page such as explorer.htm or admin.htm.

Each value must be URL-encoded by the client. Order of the parameters does not matter.

If the signature is found valid, the CMC creates an authenticated session for the Vault user, allowing the client to skip the login page and access to a CMC interior page.

How to Create the Signature

The portal server can create the signature by the following steps.

  1. Assemble the query string.

    • querystring = "user=USERID&group=GROUPID&timestamp=TIMESTAMP"

      Note When using the querystring to create the signature, do not URL-encode the querystring. Also do not reorder the items. (By contrast, when the client subsequently submits the SSO secure login request to the CMC, it’s desirable to URL encode the request querystring.)
  2. Calculate one-way hash for the querystring using the standard HmacSHA1 and the CMC SSO shared key. The shared key is configured by mts-ui.properties: sso.shared.key.

    • hashresult = HmacSHA1(querystring, sharedkey)

  3. Base64 encode the resulting hash.

    • base64string = Base64Encode(hashresult)

  4. URI encode the base64 encoded hash result.

    • signature = encodeURIComponent(base64string)

For a sample of a Python script that uses the one-way hash login API, see Nicman Vault SSO Sample Script.

Access to a CMC’s Interior Page

After creating the signature, the portal server can return an HTML page with a hyperlink to the CMC SSO secure login API. The following example will display CMC’s Data Explorer page (explorer.htm) embedded in the inline frame on the portal’s page.

<iframe src="https://<cmc_FQDN>:<cmc_port>/Vault/ssosecurelogin.htm
?user=USERID&group=GROUPID&timestamp=TIMESTAMP&signature=SIG
&redirect=explorer.htm"></iframe>
CMC SSO Secure Login HTTP Response

If redirect=RELATIVE_OR_ABSOLUTE_URL is given, the CMC’s SSO secure login API returns an HTTP redirect response.

  • If the request was successful, the redirect response will take the client to the URL specified by redirect.

  • If the request failed, the redirect response will take the client to the CMC’s Login panel.

If redirect=RELATIVE_OR_ABSOLUTE_URL is not given, the CMC’s SSO secure login API returns an HTTP response with content-type "text/plain".

  • If the request was successful, the HTTP response status is 200 OK.

  • If the request failed, a 400 BAD REQUEST status is returned, along with a plain text status description. Possible reasons for failure include:

    • Missing required parameters

    • SSO token already exists (request is ignored)

    • Timestamp in request is outside of configured tolerance range

    • Invalid signature

    • Invalid credentials (group ID and/or user ID is invalid)

CMC Logout

This API method allows for immediately invalidating the CMC session.

https://<cmc_FQDN>:<cmc_port>/Vault/logout.htm&redirect=RELATIVE_OR_ABSOLUTE_URL
  • redirect: This optional parameter can be used to redirect the client to the URL after logging out from the CMC. It is typically set to a portal page. The URL must be URL-encoded by the client.

CMC Logout HTTP Response

If redirect=RELATIVE_OR_ABSOLUTE_URL is given, the CMC’s logout API returns an HTTP redirect response to take the client to the given URL after logging out from the CMC.

If redirect=RELATIVE_OR_ABSOLUTE_URL is not given, the CMC’s logout API returns an HTTP redirect response to take the client to the CMC’s Login panel.

Logging Out from the CMC and Portal at Once

You may want the logout link on the portal page to also trigger logout from the CMC. You can achieve this by using redrect parameter.

For example, if you have the portal’s logout link like this:

<a href="/auth/logout">Logout</a>

You can change it to the following:

<a href="https://<cmc_FQDN>:<cmc_port>/Vault/logout.htm
?redirect=https:%2F%2F<portal_FQDN>:<portal_port>%2Fauth%2Flogout">Logout</a>
  • The redirect URL must be an absolute URL including the protocol (e.g. https://) and portal’s FQDN.

  • The redirect URL must be URL-encoded.

9.2.3. Nicman Vault SSO Sample Script

This section shows a sample script for Nicman Vault SSO integration, using the method described above.

Call the CMC SSO Secure Login API: Python Example

Below is a sample Python script that outputs a Vault SSO secure login URL for use with the one-way hash method of having the CMC create a cookie. The script also creates an SSO logout URL.

#!/usr/bin/python

import time
import hmac
import hashlib
import base64
import urllib


# TODO: Move these config options to configuration file
SSO_DOMAIN = 'cmc.nicmanlab.com'
SSO_PORT = 8443
SSO_KEY = 'aa2gh3t7rx6d'

# TODO: Dynamically choose user/group based on the user
# and group you want to login using.
SSO_USER = 'sso@group'
SSO_GROUP = 'ssogroup'

# Do Not Change
SSO_PROTO = 'https://'
SSO_PATH = 'Vault/ssosecurelogin.htm'
SSO_LOGOUT_PATH = 'Vault/ssologout.htm'



def sso_sig(user, group, timestamp):
    # query string with no urlencoding for signature
    signme = 'user=%s&group=%s&timestamp=%s' % (user, group, timestamp)
    hmacsha1 = hmac.new(SSO_KEY, signme, hashlib.sha1).digest()
    return base64.b64encode(hmacsha1)


def sso_url(user, group):
    timestamp = int(time.time() * 1000)
    signature = sso_sig(user, group, timestamp)
    params = {'user': user,
              'group': group,
              'timestamp': timestamp,
              'signature': signature}
    query = urllib.urlencode(params)
    url = '%s%s:%d/%s?%s' % (SSO_PROTO, SSO_DOMAIN, SSO_PORT, SSO_PATH, query)
    return url


def sso_logout_url():
    url = '%s%s:%d/%s' % (SSO_PROTO, SSO_DOMAIN, SSO_PORT, SSO_LOGOUT_PATH)
    return url


print 'login: ' + sso_url(SSO_USER, SSO_GROUP)
print '\nlogout: ' + sso_logout_url()
Note The sample script hard-codes the SSO secret key, which is not advisable for actual practice. In practice, you should keep the secret key safely on the server side.

Confidentiality Notice

The information contained in this document is confidential to, and is the intellectual property of, Nicman Group Neither this document nor any information contained herein may be (1) used in any manner other than to support the use of Vault software in accordance with a valid license obtained from Nicman Group or (2) reproduced, disclosed or otherwise provided to others under any circumstances, without the prior written permission of Nicman Group. Without limiting the foregoing, use of any information contained in this document in connection with the development of a product or service that may be competitive with Vault software is strictly prohibited. Any permitted reproduction of this document or any portion hereof must be accompanied by this legend.

Connect with Us on LinkedIn