/// Load Certificate from the given file path.
/// </summary>
/// <param name="filePath">The path of certificate file to be loaded.</param>
+ /// <returns>Loaded certificate class instance.</returns>
+ /// <exception cref="InvalidOperationException">Invalid certificate file format. Provided file path does not exist or cannot be accessed.</exception>
static public Certificate Load(string filePath)
{
IntPtr ptr = new IntPtr();
/// <summary>
/// When overridden in a derived class, executes the code required to free the handle.
/// </summary>
- /// <returns>true if the handle is released successfully</returns>
+ /// <returns>true if the handle is released successfully.</returns>
protected override bool ReleaseHandle()
{
if (IsInvalid) // do not release
/// </summary>
/// <param name="alias">The name of a certificate to retrieve.</param>
/// <param name="password">The password used in decrypting a certificate value.
- /// If password of policy is provided in SaveCertificate(), the same password should be provided
+ /// If password of policy is provided in SaveCertificate(), the same password should be provided.
/// </param>
/// <returns>A certificate specified by alias.</returns>
+ /// <exception cref="ArgumentException">Alias argument is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// Certificate does not exist with the alias or certificate-protecting password isn't matched.
+ /// </exception>
static public Certificate Get(string alias, string password)
{
IntPtr ptr = new IntPtr();
/// <summary>
/// Gets all alias of certificates which the client can access.
/// </summary>
- /// <returns>all alias of certificates which the client can access.</returns>
+ /// <returns>All alias of certificates which the client can access.</returns>
+ /// <exception cref="ArgumentException">No alias to get.</exception>
static public IEnumerable<string> GetAliases()
{
IntPtr ptr = new IntPtr();
/// <param name="alias">The name of a certificate to be stored.</param>
/// <param name="cert">The certificate's binary value to be stored.</param>
/// <param name="policy">The policy about how to store a certificate securely.</param>
+ /// <exception cref="ArgumentException">Alias argument is null or invalid format. cert argument is invalid format.</exception>
+ /// <exception cref="InvalidOperationException">Certificate with alias does already exist.</exception>
static public void Save(string alias, Certificate cert, Policy policy)
{
int ret = Interop.CkmcManager.SaveCert(alias, cert.ToCkmcCert(), policy.ToCkmcPolicy());
/// <param name="certificate">The certificate to be verified.</param>
/// <param name="untrustedCertificates">The untrusted CA certificates to be used in verifying a certificate chain.</param>
/// <returns>A newly created certificate chain.</returns>
+ /// <exception cref="ArgumentException">Some of certificate in arguments is invalid.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// Some of certificate in arguments is expired or not valid yet.
+ /// Certificate cannot build chain.
+ /// Root certificate is not in trusted system certificate store.
+ /// </exception>
/// <remarks>The trusted root certificate of the chain should exist in the system's certificate storage.</remarks>
+ /// <remarks>The trusted root certificate of the chain in system's certificate storage is added to the certificate chain.</remarks>
static public IEnumerable<Certificate> GetCertificateChain(Certificate certificate,
IEnumerable<Certificate> untrustedCertificates)
{
/// <param name="trustedCertificates">The trusted CA certificates to be used in verifying a certificate chain.</param>
/// <param name="useTrustedSystemCertificates">The flag indicating the use of the trusted root certificates in the system's certificate storage.</param>
/// <returns>A newly created certificate chain.</returns>
+ /// <exception cref="ArgumentException">Some of certificate in arguments is invalid.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// Some of certificate in arguments is expired or not valid yet.
+ /// Certificate cannot build chain.
+ /// Root certificate is not in trusted system certificate store.
+ /// </exception>
+ /// <remarks>The trusted root certificate of the chain in system's certificate storage is added to the certificate chain.</remarks>
static public IEnumerable<Certificate> GetCertificateChain(Certificate certificate,
IEnumerable<Certificate> untrustedCertificates,
IEnumerable<Certificate> trustedCertificates,
/// </summary>
/// <param name="certificateChain">Valid certificate chain to perform OCSP check.</param>
/// <returns>A status result of OCSP check.</returns>
+ /// <exception cref="ArgumentException">certificateChain is not valid chain or certificate.</exception>
+ /// <exception cref="InvalidOperationException">some of certificate in chain is expired or not valid yet.</exception>
static public OcspStatus CheckOcsp(IEnumerable<Certificate> certificateChain)
{
int ocspStatus = (int)OcspStatus.Good;
/// <param name="cipherText">Data to be decrypted (some algorithms may require additional
/// information embedded in encrypted data.AES GCM is an example).</param>
/// <returns>Decrypted data.</returns>
+ /// <exception cref="ArgumentException">
+ /// Mandatory algorithm parameter is missing or invalid.
+ /// Optional algorithm parameter is invalid.
+ /// </exception>
+ /// <exception cref="InvalidOperationException">
+ /// Key-protecting password isn't matched.
+ /// Key does not exist with keyAlias.
+ /// </exception>
/// <remarks>The key type specified by keyAlias should be compatible with the algorithm specified in Parameters.</remarks>
public byte[] Decrypt(string keyAlias, string password, byte[] cipherText)
{
/// For RSA the size must be smaller or equal to (key_size_in bytes - 42).
/// Example: for 1024 RSA key the maximum data size is 1024/8 - 42 = 86.</param>
/// <returns>Encrypted data.</returns>
+ /// <exception cref="ArgumentException">
+ /// Mandatory algorithm parameter is missing or invalid.
+ /// Optional algorithm parameter is invalid.
+ /// </exception>
+ /// <exception cref="InvalidOperationException">
+ /// Key-protecting password isn't matched.
+ /// Key does not exist with keyAlias.
+ /// </exception>
/// <remarks>The key type specified by keyAlias should be compatible with the algorithm specified in Parameters.</remarks>
public byte[] Encrypt(string keyAlias, string password, byte[] plainText)
{
/// </summary>
/// <param name="name">Parameter name.</param>
/// <param name="value">Parameter value.</param>
+ /// <exception cref="ArgumentException">CipherParameterName is invalid.</exception>
protected void Add(CipherParameterName name, long value)
{
int ret = Interop.CkmcTypes.ParamListSetInteger(PtrCkmcParamList, (int)name, value);
/// </summary>
/// <param name="name">Parameter name.</param>
/// <param name="value">Parameter value.</param>
+ /// <exception cref="ArgumentException">CipherParameterName is invalid.</exception>
protected void Add(CipherParameterName name, byte[] value)
{
Interop.CkmcRawBuffer rawBuff = new Interop.CkmcRawBuffer(new PinnedObject(value), value.Length);
/// Gets integer parameter.
/// </summary>
/// <param name="name">Parameter name.</param>
+ /// <exception cref="ArgumentException">
+ /// CipherParameterName is invalid.
+ /// No parameter set with the name.
+ /// </exception>
public long GetInteger(CipherParameterName name)
{
long value = 0;
/// Gets byte array parameter.
/// </summary>
/// <param name="name">Parameter name.</param>
+ /// <exception cref="ArgumentException">
+ /// CipherParameterName is invalid.
+ /// No parameter set with the name.
+ /// </exception>
public byte[] GetBuffer(CipherParameterName name)
{
IntPtr ptr = new IntPtr();
/// <param name="password">The password used in decrypting a private key value.</param>
/// <param name="message">The message that is signed with a private key.</param>
/// <returns>A newly created signature.</returns>
+ /// <exception cref="ArgumentException">privateKeyAlias is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// Key-protecting password isn't matched.
+ /// Key does not exist with privateKeyAlias.
+ /// </exception>
/// <remarks>The key type specified by privateKeyAlias should be compatible with the algorithm specified in Parameters.</remarks>
/// <remarks>If password of policy is provided during storing a key, the same password should be provided.</remarks>
public byte[] Sign(string privateKeyAlias, string password, byte[] message)
/// <param name="password">The password used in decrypting a public key value.</param>
/// <param name="message">The input on which the signature is created.</param>
/// <param name="signature">The signature that is verified with public key.</param>
- /// <returns>The signature statue. True is returned when the signature is valid</returns>
+ /// <returns>The signature status. True is returned when the signature is valid.</returns>
+ /// <exception cref="ArgumentException">publicKeyAlias is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// Key-protecting password isn't matched.
+ /// Key does not exist with publicKeyAlias.
+ /// </exception>
/// <remarks>The key type specified by publicKeyAlias should be compatible with the algorithm specified in Parameters.</remarks>
/// <remarks>If password of policy is provided during storing a key, the same password should be provided.</remarks>
public bool Verify(string publicKeyAlias, string password, byte[] message, byte[] signature)
/// </summary>
/// <param name="alias">The name of a certificate to retrieve.</param>
/// <param name="password">The password used in decrypting a data value.
- /// If password of policy is provided in SaveData(), the same password should be provided
+ /// If password of policy is provided in SaveData(), the same password should be provided.
/// </param>
- /// <returns>data specified by alias.</returns>
+ /// <returns>Data specified by alias.</returns>
+ /// <exception cref="ArgumentException">Alias argument is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// Data does not exist with the alias or data-protecting password isn't matched.
+ /// </exception>
static public byte[] Get(string alias, string password)
{
IntPtr ptr = new IntPtr();
/// <summary>
/// Gets all alias of data which the client can access.
/// </summary>
- /// <returns>all alias of data which the client can access.</returns>
+ /// <returns>All alias of data which the client can access.</returns>
+ /// <exception cref="ArgumentException">No alias to get.</exception>
static public IEnumerable<string> GetAliases()
{
IntPtr ptr = new IntPtr();
/// <param name="alias">The name of data to be stored.</param>
/// <param name="data">The binary value to be stored.</param>
/// <param name="policy">The policy about how to store data securely.</param>
+ /// <exception cref="ArgumentException">Alias argument is null or invalid format. Data policy cannot be unextractable.</exception>
+ /// <exception cref="InvalidOperationException">Data with alias does already exist.</exception>
static public void Save(string alias, byte[] data, Policy policy)
{
Interop.CkmcRawBuffer rawBuff = new Interop.CkmcRawBuffer(new PinnedObject(data), data.Length);
/// Gets a key from secure repository.
/// </summary>
/// <param name="alias">The name of a key to retrieve.</param>
- /// <param name="password">The password used in decrypting a key value.
- /// If password of policy is provided in SaveKey(), the same password should be provided
+ /// <param name="password">
+ /// The password used in decrypting a key value.
+ /// If password of policy is provided in SaveKey(), the same password should be provided.
/// </param>
/// <returns>A key specified by alias.</returns>
+ /// <exception cref="ArgumentException">Alias argument is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// Key does not exist with the alias or key-protecting password isn't matched.
+ /// </exception>
static public Key Get(string alias, string password)
{
IntPtr ptr = new IntPtr();
/// <summary>
/// Gets all alias of keys which the client can access.
/// </summary>
- /// <returns>all alias of keys which the client can access.</returns>
+ /// <returns>All alias of keys which the client can access.</returns>
+ /// <exception cref="ArgumentException">No alias to get.</exception>
static public IEnumerable<string> GetAliases()
{
IntPtr ptr = new IntPtr();
/// <param name="alias">The name of a key to be stored.</param>
/// <param name="key">The key's binary value to be stored.</param>
/// <param name="policy">The policy about how to store a key securely.</param>
+ /// <exception cref="ArgumentException">Alias argument is null or invalid format. key argument is invalid format.</exception>
+ /// <exception cref="InvalidOperationException">Key with alias does already exist.</exception>
/// <remarks>Type in key may be set to KeyType.None as an input. Type is determined inside secure reposioty during storing keys.</remarks>
/// <remarks>If password in policy is provided, the key is additionally encrypted with the password in policy.</remarks>
static public void Save(string alias, Key key, Policy policy)
/// <param name="publicKeyAlias">The name of public key to be stored.</param>
/// <param name="privateKeyPolicy">The policy about how to store a private key securely.</param>
/// <param name="publicKeyPolicy">The policy about how to store a public key securely.</param>
+ /// <exception cref="ArgumentException">size is invalid. privateKeyAlias or publicKeyAlias is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">Key with privateKeyAlias or publicKeyAlias does already exist.</exception>
/// <remarks>If password in policy is provided, the key is additionally encrypted with the password in policy.</remarks>
static public void CreateRsaKeyPair(int size, string privateKeyAlias, string publicKeyAlias,
Policy privateKeyPolicy, Policy publicKeyPolicy)
/// <param name="publicKeyAlias">The name of public key to be stored.</param>
/// <param name="privateKeyPolicy">The policy about how to store a private key securely.</param>
/// <param name="publicKeyPolicy">The policy about how to store a public key securely.</param>
+ /// <exception cref="ArgumentException">size is invalid. privateKeyAlias or publicKeyAlias is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">Key with privateKeyAlias or publicKeyAlias does already exist.</exception>
/// <remarks>If password in policy is provided, the key is additionally encrypted with the password in policy.</remarks>
static public void CreateDsaKeyPair(int size, string privateKeyAlias, string publicKeyAlias,
Policy privateKeyPolicy, Policy publicKeyPolicy)
/// <param name="publicKeyAlias">The name of public key to be stored.</param>
/// <param name="privateKeyPolicy">The policy about how to store a private key securely.</param>
/// <param name="publicKeyPolicy">The policy about how to store a public key securely.</param>
+ /// <exception cref="ArgumentException">Elliptic curve type is invalid. privateKeyAlias or publicKeyAlias is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">Key with privateKeyAlias or publicKeyAlias does already exist.</exception>
/// <remarks>If password in policy is provided, the key is additionally encrypted with the password in policy.</remarks>
static public void CreateEcdsaKeyPair(EllipticCurveType type, string privateKeyAlias, string publicKeyAlias,
Policy privateKeyPolicy, Policy publicKeyPolicy)
/// <param name="size">The size of key strength to be created. 128, 192 and256 are supported.</param>
/// <param name="keyAlias">The name of key to be stored.</param>
/// <param name="policy">The policy about how to store the key securely.</param>
+ /// <exception cref="ArgumentException">Key size is invalid. keyAlias is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">Key with privateKeyAlias or publicKeyAlias does already exist.</exception>
/// <remarks>If password in policy is provided, the key is additionally encrypted with the password in policy.</remarks>
static public void CreateAesKey(int size, string keyAlias, Policy policy)
{
* limitations under the License
*/
+using System;
+
namespace Tizen.Security.SecureRepository
{
/// <summary>
/// Removes a an entry (no matter of type) from the key manager.
/// </summary>
/// <param name="alias">Item alias to be removed.</param>
+ /// <exception cref="ArgumentException">alias is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">alias does not exist.</exception>
/// <remarks>To remove item, client must have remove permission to the specified item.</remarks>
/// <remarks>The item owner can remove by default.</remarks>
static public void RemoveAlias(string alias)
/// <param name="alias">Item alias for which access will be granted.</param>
/// <param name="otherPackageId">Package id of the application that will gain access rights.</param>
/// <param name="permissions">Mask of permissions(Permission enum) granted for an application with otherPackageId.</param>
+ /// <exception cref="ArgumentException">alias or otherPackageId is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">alias does not exist.</exception>
/// <remarks>Data identified by alias should exist.</remarks>
/// <remarks>The item owner can set permissions.</remarks>
static public void SetPermission(string alias, string otherPackageId, int permissions)
/// <param name="filePath">The path of PKCS12 file to be loaded.</param>
/// <param name="filePassword">The passphrase used to decrypt the PCKS12 file.
/// If PKCS12 file is not encrypted, passphrase can be null.</param>
+ /// <exception cref="ArgumentException">filePath is null.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// No file on filePath.
+ /// No permission to access file.
+ /// File is invalid PKCS12 format.
+ /// File cannot be extracted with provided filePassword.
+ /// </exception>
static public Pkcs12 Load(string filePath, string filePassword)
{
IntPtr ptr = new IntPtr();
/// If password of certificatePolicy is provided in SavePkcs12(), the same password should be provided
/// </param>
/// <returns>A Pkcs12 data specified by alias.</returns>
+ /// <exception cref="ArgumentException">Alias argument is null or invalid format.</exception>
+ /// <exception cref="InvalidOperationException">
+ /// Pkcs12 does not exist with the alias.
+ /// Optional password of key in Pkcs12 isn't matched.
+ /// Optional password of certificate in Pkcs12 isn't matched.
+ /// </exception>
static public Pkcs12 Get(string alias, string keyPassword, string cerificatePassword)
{
IntPtr ptr = new IntPtr();
/// <param name="pkcs12">The pkcs12 data to be stored.</param>
/// <param name="keyPolicy">The policy about how to store pkcs's private key.</param>
/// <param name="certificatePolicy">The policy about how to store pkcs's certificate.</param>
+ /// <exception cref="ArgumentException">Alias argument is null or invalid format. Pkcs12 argument is invalid format.</exception>
+ /// <exception cref="InvalidOperationException">Pkcs12 with alias does already exist.</exception>
static public void Save(string alias, Pkcs12 pkcs12, Policy keyPolicy, Policy certificatePolicy)
{
int ret = Interop.CkmcManager.SavePkcs12(alias,