Skip to content

Commit

Permalink
docs: updated documentation for encryption APIs (minio#577)
Browse files Browse the repository at this point in the history
  • Loading branch information
@nitisht @harshavardhana
nitisht authored and harshavardhana committed May 21, 2017
1 parent d268683 commit 73ca5e5
Show file tree
Hide file tree
Showing 2 changed files with 40 additions and 48 deletions.
49 changes: 14 additions & 35 deletions api/src/main/java/io/minio/MinioClient.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1588,13 +1588,11 @@ public void getObject(String bucketName, String objectName, String fileName)
}

/**
* Gets entire encrypted object's data as {@link InputStream} in given bucket, then returns CipherInputStream.
* CipherInputStream is composed of an InputStream and a Cipher so that read() methods return data that are read in
* from the underlying InputStream but have been additionally processed by the Cipher. The Cipher is initialized for
* decryption, the CipherInputStream will attempt to read in data and decrypt them, before returning the decrypted
* data.
* Returns {@link InputStream} containing decrypted data of given object. Secret key passed to this method should be
* the same as the one used for putObject() operation.
*
* <p>
* The CipherInputStream must be closed after use else the connection will remain open.
* The returned InputStream must be closed after use else the connection will remain open.
* </p>
* <b>Example:</b>
*
Expand Down Expand Up @@ -1664,19 +1662,17 @@ public InputStream getObject(String bucketName, String objectName, SecretKey key
}

/**
* Gets entire encrypted object's data as {@link InputStream} in given bucket, then returns CipherInputStream.
* CipherInputStream is composed of an InputStream and a Cipher so that read() methods return data that are read in
* from the underlying InputStream but have been additionally processed by the Cipher. The Cipher is initialized for
* decryption, the CipherInputStream will attempt to read in data and decrypt them, before returning the decrypted
* data.
* Returns {@link InputStream} containing decrypted data of given object. Keypair passed to this method should be the
* same as the one used for putObject() operation.
*
* <p>
* The CipherInputStream must be closed after use else the connection will remain open.
* The returned InputStream must be closed after use else the connection will remain open.
* </p>
*
* <b>Example:</b>
*
* <pre>
* {
*
* // Get object with symmetric master key used in putObject
* InputStream stream = minioClient.getObject("my-bucketname", "my-objectname", keypair);
* byte[] buf = new byte[16384];
Expand Down Expand Up @@ -3135,18 +3131,11 @@ public void putObject(String bucketName, String objectName, InputStream stream,
}

/**
* Takes data from given stream, encrypts it using a random content key and upload it as object to given bucket. Also
* uploads the encrypted content key and iv as header of the encrypted object. The content key is encrypted using the
* master key.
* Uploads encrypted data from given stream as object to given bucket where data is encrypted on the fly using passed
* secret key.
*
* <p>
* If the object is larger than 5MB, the client will automatically use a multipart session.
*
* If the session fails, the user may attempt to re-upload the object by attempting to create the exact same object
* again. The client will examine all parts of any current upload session and attempt to reuse the session
* automatically. If a mismatch is discovered, the upload will fail before uploading any more data. Otherwise, it will
* resume uploading where the session left off.
*
* </p>
* <b>Example:</b><br>
*
Expand Down Expand Up @@ -3245,22 +3234,12 @@ public void putObject(String bucketName, String objectName, InputStream stream,
}

/**
* Takes data from given stream, encrypts it using a random content key and upload it as object to given bucket. Also
* uploads the encrypted content key and iv as header of the encrypted object. The content key is encrypted using the
* master key.
* Uploads encrypted data from given stream as object to given bucket where data is encrypted on the fly using passed
* keypair.
*
* <p>
* If the object is larger than 5MB, the client will automatically use a multipart session.
* </p>
* <p>
* If the session fails, the user may attempt to re-upload the object by attempting to create the exact same object
* again. The client will examine all parts of any current upload session and attempt to reuse the session
* automatically. If a mismatch is discovered, the upload will fail before uploading any more data. Otherwise, it will
* resume uploading where the session left off.
* </p>
* <p>
* If the multipart session fails, the user is responsible for resuming or removing the session.
* </p>
* </p>
* <b>Example:</b><br>
*
* <pre>
Expand Down
39 changes: 26 additions & 13 deletions docs/API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -709,9 +709,13 @@ try {

`public CipherInputStream getObject(String bucketName, String objectName, SecretKey key)`

Gets entire encrypted object's data, then returns InputStream. InputStream is composed of an InputStream and a Cipher so that read() methods return data that are read in from the underlying InputStream but have been additionally processed by the Cipher. The EncryptionMaterials object used for getObject should be the same as the one used for corresponding putObject operation.
Gets entire encrypted object's data as InputStream in given bucket, then decrypts the content key
associated with the encrypted object using the master key passed. Then creates a CipherInputStream composed of an
InputStream and a Cipher. The Cipher is initialized for decryption using the content key, so the CipherInputStream
will attempt to read in data and decrypt them, before returning the decrypted data. So that read() methods return
processed, plain object.

CipherInputStream should be closed after use, else connection remains open.
The CipherInputStream must be closed after use else the connection will remain open.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#getObject-java.lang.String-java.lang.String-javax.crypto.SecretKey-)

Expand All @@ -722,7 +726,7 @@ __Parameters__
|:--- |:--- |:--- |
| ``bucketName`` | _String_ | Name of the bucket. |
| ``objectName`` | _String_ | Object name in the bucket. |
| ``key`` | _SecretKey_ | An object of type [SecretKey](https://docs.oracle.com/javase/7/docs/api/javax/crypto/SecretKey.html) or RSA [KeyPair](https://docs.oracle.com/javase/7/docs/api/java/security/KeyPair.html). |
| ``key`` | _SecretKey_ | An object of type [SecretKey](https://docs.oracle.com/javase/7/docs/api/javax/crypto/SecretKey.html). |

| Return Type | Exceptions |
|:--- |:--- |
Expand Down Expand Up @@ -775,17 +779,20 @@ try {
<a name="getObject"></a>
### getObject(String bucketName, String objectName, KeyPair key)

`public CipherInputStream getObject(String bucketName, String objectName, KeyPair key)`
`public InputStream getObject(String bucketName, String objectName, KeyPair key)`

Gets entire encrypted object's data, then returns InputStream. InputStream is composed of an InputStream and a Cipher so that read() methods return data that are read in from the underlying InputStream but have been additionally processed by the Cipher.
Gets entire encrypted object's data as InputStream in given bucket, then decrypts the content key
associated with the encrypted object using the master key pair passed. Then creates a CipherInputStream composed of an
InputStream and a Cipher. The Cipher is initialized for decryption using the content key, so the CipherInputStream
will attempt to read in data and decrypt them, before returning the decrypted data. So that read() methods return
processed, plain object.

CipherInputStream should be closed after use, else connection remains open.
The CipherInputStream must be closed after use else the connection will remain open.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#getObject-java.lang.String-java.lang.String-java.security.KeyPair-)

__Parameters__


|Param | Type | Description |
|:--- |:--- |:--- |
| ``bucketName`` | _String_ | Name of the bucket. |
Expand Down Expand Up @@ -956,7 +963,11 @@ try {
`public void putObject(String bucketName, String objectName, InputStream stream, long size, String contentType,
SecretKey key)`

Encrypts and then uploads an object from an InputStream.
Takes data from given stream, encrypts it using a random content key and uploads it as object to given bucket. Also
uploads the encrypted content key and iv as header of the encrypted object. The content key is encrypted using the
master key passed to this function.

If the object is larger than 525MB, the client will automatically perform multi part upload.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#putObject-java.lang.String-java.lang.String-java.io.InputStream-long-java.lang.String-javax.crypto.SecretKey-)

Expand Down Expand Up @@ -1029,14 +1040,18 @@ try {
```

<a name="putObject"></a>
### putObject(String bucketName, String objectName, InputStream stream, long size, String contentType, SecretKey key)
### putObject(String bucketName, String objectName, InputStream stream, long size, String contentType, KeyPair key)

`public void putObject(String bucketName, String objectName, InputStream stream, long size, String contentType,
KeyPair key)`

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#putObject-java.lang.String-java.lang.String-java.io.InputStream-long-java.lang.String-java.security.KeyPair-)
Takes data from given stream, encrypts it using a random content key and uploads it as object to given bucket. Also
uploads the encrypted content key and iv as header of the encrypted object. The content key is encrypted using the
master key pair passed to this function.

Encrypts and then uploads an object from an InputStream.
If the object is larger than 525MB, the client will automatically perform multi part upload.

[View Javadoc](http://minio.github.io/minio-java/io/minio/MinioClient.html#putObject-java.lang.String-java.lang.String-java.io.InputStream-long-java.lang.String-java.security.KeyPair-)

__Parameters__

Expand All @@ -1050,8 +1065,6 @@ __Parameters__
| ``contentType`` | _String_ | Content type of the stream. |
| ``key`` | _KeyPair_ | An object of type initialized RSA [KeyPair](https://docs.oracle.com/javase/7/docs/api/java/security/KeyPair.html). |

putObject-java.lang.String-java.lang.String-java.io.InputStream-long-java.lang.String-java.security.KeyPair-

| Return Type | Exceptions |
|:--- |:--- |
| None | Listed Exceptions: |
Expand Down

0 comments on commit 73ca5e5

Please sign in to comment.