Access and authentication
The Hitachi API for Amazon S3 is an HTTP-based API. This means that you use URLs to identify tenants, buckets, and objects. Every S3 compatible request for access to HCP must include the URL for the service point, bucket, or object that’s the target of the request.
With every S3 compatible request, you also need to either provide credentials for the user account you’re using or request anonymous access. If HCP determines that credentials you provide correspond to a valid user account and that the user account has the applicable permissions for the requested operation, you become an authenticated user.
HCP supports three methods of user authentication for the S3 compatible API: Amazon Web Services™ (AWS™), Active Directory (AD), and HCP. With AWS authentication, HCP follows the Amazon S3 method of authenticating users. With AD authentication, HCP authenticates users with AD. With HCP authentication, HCP uses its own standard method. If you’re using the S3 compatible API to develop applications that are compatible with Amazon S3, you should use AWS authentication.
This section of the Help describes the URLs you can use in S3 compatible requests when using AWS or AD authentication. It also explains how to provide credentials or request anonymous access with that authentication method.
- All the examples of S3 compatible requests in this book assume AWS authentication.
- To use a recognized Active Directory user account for access to HCP through the S3 compatible API, applications can use AWS authentication with the AD identifier. Alternatively, they can use the SPNEGO protocol to negotiate the AD user authentication themselves.
URLs for access to HCP
With the S3 compatible API, the service point (also called the endpoint) is a tenant. Every request you make to access HCP using the S3 compatible API is made within the context of a tenant.
The URL in a request identifies the target of the request. This target can be the tenant, a bucket within the tenant, or an object within a bucket within the tenant. The format you use for a URL depends on the target of the request and the authentication method being used.
An HCP system can have multiple tenants and, therefore, multiple service points. Each tenant has its own default configuration settings for new buckets. Buckets, therefore, can have different characteristics depending on the tenants within which you create them.
Each tenant also has its own set of user accounts. For access that requires you to be an authenticated user, you need to use a user account that’s defined for the applicable tenant.
Targeting a tenant
In an S3 compatible request that uses AWS authentication, if the target is a tenant, you use a URL in this format:
http[s]://tenant-name.hcp-domain-name
Here’s an example in which the tenant name is europe:
https://europe.hcp.example.com
Targeting a bucket
In an S3 compatible request that uses AWS authentication, if the target is a bucket, you use a URL in either of these formats:
http[s]://bucket-name.tenant-name.hcp-domain-name http[s]://tenant-name.hcp-domain-name/bucket-name
In the first format above, the bucket name is part of the hostname. In the second format, the bucket name follows the hostname.
Here’s are examples in which the tenant name is europe and the bucket name is finance:
https://finance.europe.hcp.example.com https://europe.hcp.example.com/finance
Targeting an object
In an S3 compatible request that uses AWS authentication, if the target is an object, you use a URL in either of these formats:
http[s]://bucket-name.tenant-name.hcp-domain-name/object-name http[s]://tenant-name.hcp-domain-name/bucket-name/object-name
In the first format above, the bucket name is part of the hostname. In the second format, the bucket name follows the hostname.
Here are examples in which the tenant name is europe, the bucket name is finance, and the object name is Q4_2019.ppt:
https://finance.europe.hcp.example.com/Q4_2019.ppt https://europe.hcp.example.com/finance/Q4_2019.ppt
Using SSL security
When you create a bucket or list the buckets you own, HCP does not require the use of SSL security with the S3 compatible request; that is, you can start the URL in the request with either HTTP or HTTPS. Whether the use of SSL security with other S3 compatible requests is required, optional, or not supported depends on the configuration of the S3 compatible API for the target bucket.
By default, the use of SSL security is optional for requests for operations other than creating a bucket or listing the buckets you own. You cannot use the S3 compatible API to change this configuration. However, tenant administrators can use other HCP interfaces to reconfigure the S3 compatible API to require or not support the use of SSL security.
Using an IP address in a URL
Normally, you let HCP choose the node on which to process an S3 compatible API request. You can, however, use an IP address in the request URL to access the system on a specific node. To do this, you replace the fully qualified hostname in the URL with the IP address of an HCP node.
When you use an IP address in a URL, you also need to specify the fully qualified hostname in an HTTP Host request header.
Here’s an example of an s3curl command that uses a URL with an IP address and a Host header that identifies the finance bucket:
./s3curl.pl --id=lgreen --put=Q4_2019.ppt -- -k -H "Host: finance.europe.hcp.example.com" "https://192.168.210.16/quarterly_rpts/Q4_2019.ppt"
Here’s a command that does the same thing as the command above but uses the format in which the bucket name follows the URL:
./s3curl.pl --id=lgreen --put=Q4_2019.ppt -- -k -H "Host: europe.hcp.example.com" "https://192.168.210.16/finance/quarterly_rpts/Q4_2019.ppt"
Using a hosts file
Typically, HCP is included as a subdomain in your DNS. If this is not the case, for access to the system, you need to use the tenant domain name in the URL and use a hosts file to define mappings of one or more node IP addresses to that domain name.
The location of the hosts file depends on the client operating system:
- On Windows, by default: c:\windows\system32\drivers\etc\hosts
- On Unix: /etc/hosts
- On Mac OS® X: /private/etc/hosts
Each entry in a hosts file is a mapping of an IP address to a hostname. For an HCP tenant, the hostname must be the fully qualified domain name (FQDN) for the tenant.
Each hosts file entry you create for access to a tenant must include:
- An IP address of a node in the HCP system
- The FQDN of the tenant domain
For example, if the tenant domain name is finance.hcp.example.com and one of the HCP nodes has the IPv4 address 192.168.210.16 and the IPv6 address 2001:0db8::101, you could add either or both of these lines to the hosts file on the client:
192.168.210.16 finance.hcp.example.com 2001:0db8::101 finance.hcp.example.com
You can include comments in a hosts file either on separate lines or following a mapping on the same line. Each comment must start with a number sign (#). Blank lines are ignored.
In the hosts file, you can map IP addresses for any number of nodes to a single domain name. The way a client uses multiple IP address mappings for a single domain name depends on the client platform. For information about how your client handles hosts file entries that define multiple IP address mappings for a single domain name, see your client documentation.
If any of the HCP nodes listed in the hosts file are unavailable, timeouts may occur when you use a hosts file to access the system through the management API.
Here’s a sample hosts file that contains mappings for the Finance tenant for nodes with both IPv4 and IPv6 addresses:
192.168.210.16 finance.hcp.example.com 192.168.210.17 finance.hcp.example.com 192.168.210.18 finance.hcp.example.com 192.168.210.19 finance.hcp.example.com 2001:0db8::101 finance.hcp.example.com 2001:0db8::102 finance.hcp.example.com 2001:0db8::103 finance.hcp.example.com 2001:0db8::104 finance.hcp.example.com
URL considerations
The following considerations apply to URLs in S3 compatible API requests.
In the URLs you specify in S3 compatible requests:
- HTTP and HTTPS are not case sensitive.
- Hostnames are not case sensitive.
- Bucket names are not case sensitive.
- Unlike the items above, object names are case sensitive.
When using a command-line tool to access HCP through the S3 compatible API, you work in a Unix, Mac OS X, or Windows shell. Some characters in the commands you enter may have special meaning to the shell. For example, the ampersand (&) used in URLs to join multiple query parameters also often indicates that a process should be put in the background.
To avoid the possibility of the Unix, Mac OS X, or Windows shell misinterpreting special characters in a URL, always enclose the entire URL, including any query parameters, in double quotation marks.
If you’re using HTTPS in your request URLs, check with your tenant administrator as to whether you need to disable SSL certificate verification. You would need to do this if the SSL server certificate presented by the HCP system is not signed by a trusted certificate authority.
With s3curl, you disable SSL certificate verification by including ‑k or ‑‑insecure in the request command line.
Authentication
To use the S3 compatible API as an authenticated user, you need to provide credentials. These credentials must be based on the username and password for your HCP user account or, if HCP is configured to support Windows Active Directory® (AD), for an AD user account that HCP recognizes.
To provide credentials, you typically use the HTTP Authorization request header. However, HCP also accepts Active Directory authentication provided through the SPNEGO protocol. For more information about SPNEGO, see http://tools.ietf.org/html/rfc4559.
If the S3 compatible API is configured to require user authentication, you need to provide credentials with every request. If the S3 compatible API is configured to allow anonymous access, you need to either provide credentials or request anonymous access with each request.
HCP supports presigned URLs. A presigned URL uses query parameters to provide credentials. Presigned URLs allow you to temporarily share objects with other users without the need to grant those users permission to access your buckets or objects. Presigned URLs are compatible only with the AWS method of authentication.
AWS authentication
To provide credentials for AWS Version 2 authentication, you use the Authorization request header with a value in the format shown below:
Authorization: AWS access-key:signature
In this format:
access-key
The Base64-encoded username for your user account.
signature
A value calculated using your secret key and specific elements of the S3 compatible request, including the date and time of the request. Your secret key is the MD5-hashed password for your user account.
Because the signature for an S3 compatible request is based on the request contents, it differs for different requests.
Here’s an example of an Authorization header for AWS Version 2 authentication:
Authorization: AWS bGdyZWVu:vQ/rj3y0AUjWsht9M5aQw4+D0dA=
With AWS Version 4 authentication, the S3 compatible API supports both signed and unsigned payloads.
Active Directory authentication
To provide credentials for Active Directory authentication, you use the Authorization request header with a value in the format shown below:
Authorization: AD ad-user-name:ad-password
In this format:
ad-username
The AD user account username.
ad-password
The AD user account password.
Here’s an example of an Authorization header for AD authentication:
Authorization: AD lgreen@example.com:p4sswOrd
Presigned URLs
To provide credentials for AWS authentication using a presigned URL, you append these query parameters to the request URL:
AWSAccessKeyId=access-key Expires=expiration-time Signature=signature
In these parameters:
access-key
The Base64-encoded username for your user account.
expiration-time
The time the request expires, in seconds since January 1, 1970, at 00:00:00 UTC.
signature
A value calculated using your secret key and specific elements of the S3 compatible request, including the date and time the request expires.
If any part of a presigned URL is changed, the URL becomes invalid.
Here’s an example of a presigned URL:
https://finance.europe.hcp.example.com/quarterly_rpts/Q4_2019.ppt
?AWSAccessKeyId=bGdyZWVu&Expires=1363867332
&Signature=eY9lpX2KXRuW%2FrzLYU%2F5jXfjHj7%3D
Signatures
Third-party tools that are compatible with the S3 compatible API typically calculate request signatures automatically. Some of these tools can also be used to generate presigned URLs.
If you’re writing your own application, you can use an AWS SDK to calculate request signatures. For information about these SDKs, see: http://docs.aws.amazon.com/AmazonS3/latest/dev/AuthUsingAcctOrUserCredentials.html
For detailed information on calculating signatures for AWS authentication, see: http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html
Anonymous access
To request anonymous access to a bucket or object, you use the Authorization request header with the AWS authentication format. However, instead of providing credentials for a user account, you specify all_users
in place of the access key and leave the signature blank, like this:
Authorization: AWS all_users:
The colon after all_users
is required.
Invalid credentials
Regardless of how the S3 compatible API is configured, if you provide invalid credentials, HCP returns an InvalidAccessKeyId
or SignatureDoesNotMatch
error code and does not perform the requested operation:
InvalidAccessKeyId
Indicates that the access key you provided does not correspond to a valid user name.
SignatureDoesNotMatch
Indicates that the signature does not match the content of the request. This can happen if the secret key used in the signature calculation does not correspond to the password for the account with the applicable user name but can also be due to other errors.
Changing your password
If you have an HCP user account, the password for the account is initially set by a tenant administrator. You can change this password at any time, as long as you have browse or read permission for at least one bucket. For security purposes, you should change your password as soon as possible after you receive your account information.
Your password is used to calculate your secret key for use with the S3 compatible API. When you change your password, your secret key also changes.
You can use a few different HCP interfaces to change your password, as long as you have access to those interfaces. When you change your password in one interface, it changes for all HCP interfaces to which you have access.
The next procedure describes how to change your password using the Namespace Browser.
Procedure
Open a web browser window.
In the address field, enter the URL for a bucket for which the S3 compatible API requires user authentication and for which you have browse or read permission. Use this format:
http[s]://bucket-name.tenant-name.hcp-domain-name/browser
For example:https://finance.europe.hcp.example.com/browser
Either of these events happen:- If the tenant does not support AD authentication or the tenant supports AD authentication but the namespace does not support AD single sign-on, the Namespace Browser login page is displayed.
- If the tenant supports AD authentication and the S3 compatible API is configured to support AD single sign-on, a message is displayed indicating that single sign-on was not possible.
Click the Console login page link in the message to display the Namespace Browser login page.
On the Namespace Browser login page:
In the Username field, type your username.
In the Password field, type your case-sensitive password.
In the Domain field, if present, select the domain name of the HCP system.
Click Log In.
In the top right corner of the Namespace Browser window, click the Password link.
On the Change Password page:
In the Existing Password field, type your current password.
In the New Password field, type your new password.
Passwords can be up to 64 characters long, are case sensitive, and can contain any valid UTF-8 characters including white space. To be valid, a password must include at least one character from two of these three groups: alphabetic, numeric, and other. When changing your password, you cannot reuse your current password.In the Confirm New Password field, type your new password again.
Click Update Password.